io.github.AmauryDvl/serpmantics

Tools

• create_citation_check

  Test whether ChatGPT, Perplexity and Google AI Overview cite a website for one question (free tool) Asks one question to three AI answer engines (ChatGPT with web search, Perplexity, Google AI Overview) in the chosen market, and reports for each engine whether your domain is cited as a source (`cited`, a citation on your registrable domain or one of its subdomains), whether your brand is named in the answer (`mentioned`, which is NOT a citation), which of your pages are cited, an excerpt of the answer, its sources, and the domains cited instead of yours. **One answer, on one day.** This is a snapshot, not a lasting measure: AI answers change from one week to the next, and between two calls. Run the test again to compare. **Asynchronous, poll the result.** This call only starts the test and answers HTTP 202 with a `checkId` and a `pollUrl`. Call `GET /api/v1/tools/citation-check?checkId=...` every 3 seconds until `status` is `done` or `failed`; a test usually takes less than 2 minutes. MCP clients must call the `get_citation_check` tool again until the status is terminal. **Identical questions are reused for 24 hours.** The same question (case and spaces ignored) in the same market, asked less than 24 hours ago, returns the engine answers already collected, recomputed for your domain: HTTP 200 with `reused` true and `status` already `done`. Nothing is paid for again, and your daily quota is given back. **Domain.** Send a domain name or any URL of the site: it is reduced to its registrable domain (`https://www.example.co.uk/blog/` becomes `example.co.uk`). IP addresses, local names and unknown suffixes return 400 INVALID_DOMAIN. **Tiers, per UTC day.** - Without an API key, free anonymous tier: 1 test per day per IP address. - Signed-in account, or API key of an account whose plan includes API access: 10 tests per day. The API key of an account whose plan does NOT include API access does not authenticate, and the call returns 401. Remove the `Authorization` header to use the free anonymous tier instead. Quota headers: `X-RateLimit-Limit`, `X-RateLimit-Used`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time of the next UTC midnight). `Retry-After` is set on 429 and 503. A 502 or 503 answer gives the consumed quota back, and so does a 429 FREE_CAPACITY_REACHED and a 200 reused answer; SERVICE_UNAVAILABLE consumes none. **Request format.** Send the body as JSON with `Content-Type: application/json`: any other content type returns 415. Without an `Authorization` header, a request sent by a web page of another site (an `Origin` other than the SERPmantics app, or `Sec-Fetch-Site: cross-site`) returns 403. Server-to-server calls send no `Origin` header and are not affected.

  shallow
• create_eeat

  Start an E-E-A-T analysis on a guide content Starts an asynchronous E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) analysis on the HTML content provided for a given guide. The analysis runs in the background — use GET /api/v1/eeat to poll for results until `status` is `done` (or `failed`). **Note:** This endpoint uses tokens (check /api/v1/tokens-usage for the cost, might vary).

  shallow
• create_eeat_competitors

  Start an E-E-A-T analysis on a guide's top SERP competitors Starts an asynchronous E-E-A-T analysis on the top competitors of the guide's SERP. Each competitor is fetched and scored individually. Use GET /api/v1/eeat-competitors to poll for results until `pending` reaches `0`. **Token cost:** This endpoint charges `eeatCompetitorsTokensCostPerCompetitor` (see /api/v1/tokens-usage) per competitor analyzed, up to 10 competitors. Example: 10 competitors × 5 tokens = 50 tokens. 6 competitors × 5 tokens = 30 tokens. The number of competitors corresponds to the deduplicated URLs in the guide's top-10 SERP results (available via GET /api/v1/guide).

  shallow
• create_guides

  Create new guides Create one or more new guides based on provided queries. Each guide targets exactly ONE engine and ONE analysis mode, chosen with the optional `source` field (default `google`). How to request each guide type: 1. Google SERP guide (1 credit per guide): omit `source`, or pass `source: "google"`. Example payload: {"queries": ["best crm"], "lang": "en-us"} 1bis. Google AI Overview guide (1 credit per guide). Two modes, like AI engines: `source: "google_ai_overview"` builds the guide from the TEXT of Google's AI answers (AI Overview, completed with AI Mode answers) ; `source: "google_ai_overview_citations"` builds it from the content of the web SOURCES those answers cite (recommended for GEO). Same language/country parameters as a Google SERP guide, 1 credit per guide in both modes. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "google_ai_overview_citations"} 2. LLM ANSWER guide (4 credits per guide): pass the engine name alone, e.g. `source: "chatgpt"`. The guide is built from the answer text the AI generates for the query. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "chatgpt"} 3. LLM CITATIONS guide (4 credits per guide) [RECOMMENDED AI mode]: pass the engine name with the `_citations` suffix, e.g. `source: "chatgpt_citations"`. The guide is built from the content of the web pages the AI cites in its answer. Example payload: {"queries": ["best crm"], "lang": "en-us", "source": "chatgpt_citations"} Which AI mode to pick? For GEO (getting a page visible in AI answers), prefer `<engine>_citations`: AI engines send traffic by CITING pages as sources, so the winning move is to look like the pages they cite. The answer-text mode (`<engine>` alone) is mostly useful to analyze how the AI phrases its own answer. When in doubt, pick `<engine>_citations`. The same two modes exist for every AI engine (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek). To optimize the same page for several engines or modes (e.g. Google AND ChatGPT answers AND ChatGPT sources), create one guide per source value on the same query.

  shallow
• create_intent

  Generate search intent analysis for a guide Analyzes search intent for a guide and optionally analyzes provided content against that intent. **Note:** This endpoint uses tokens (check /api/v1/tokens-usage for the cost, might vary).

  shallow
• create_internal_links

  Generate internal linking suggestions for a guide Analyzes a guide and generates internal linking suggestions based on content analysis. **Note:** This endpoint uses tokens (check /api/v1/tokens-usage for the cost, might vary).

  shallow
• create_meta

  Generate SEO meta titles and descriptions for a guide Generates optimized meta titles and descriptions based on guide content analysis. **Note:** This endpoint uses tokens (check /api/v1/tokens-usage for the cost, might vary).

  shallow
• create_outline

  Generate content outline for a guide Generates a content outline based on SERP analysis for a guide. **Note:** This endpoint uses tokens (check /api/v1/tokens-usage for the cost, might vary).

  shallow
• create_persona_brief

  Generate an AI persona and brand voice brief from the pages of a website (free tool) Reads public pages of a website and produces an editorial persona and writing style brief: who writes, for whom, tone on 6 axes, vocabulary, structure, do and don't lists, verified quotes from the pages, style metrics measured on the text, and a ready-to-paste writing prompt for any AI writing tool (`brief.writingPrompt`, plus `brief.writingPromptCompact` of at most 1500 characters). **Asynchronous, poll the result.** This call only starts the job and answers HTTP 202 with a `briefId` and a `pollUrl`. Call `GET /api/v1/tools/persona-brief?briefId=...` every 3 seconds until `status` is `done` or `failed`. A brief takes about 80 seconds plus 5 seconds per page, rounded up to the half minute: about 2 min for 3 pages, 2 min 30 s for 10 pages. MCP clients must call the `get_persona_brief` tool again until the status is terminal. **Identical requests are reused for 72 hours.** The same set of URLs, in any order, with the same `outputLanguage` and the same `brandName`, returns the brief already computed instead of computing it again: HTTP 200 with `reused` true, `status` already `done`, the original `briefId` and `reusedCreatedAt`, the date of the brief it reuses. Nothing is created, and your daily quota is given back, so a reused answer costs you nothing. The pages of a reused brief are listed in the order of the original request, not in the order you just sent. Send `force` true to skip the lookup and compute a new brief, which answers 202 and consumes quota. **Addresses.** Duplicate URLs, compared once normalized, are read once. A private, local or blocked address is not refused by this call: the brief is created, and that page ends with `status` failed and `failureReason` BLOCKED_ADDRESS (the brief fails with NO_USABLE_PAGE when no other page could be read). **Tiers, per UTC day.** Every tier is capped at 10 URLs per brief since 21 September 2026. - Without an API key, free anonymous tier: 3 briefs per day per IP address, 10 URLs per brief. - Signed-in account on the web interface, plan without API access: 10 briefs per day, 10 URLs per brief. - API key of an account whose plan includes API access, pro tier: 50 briefs per day, 10 URLs per brief. The API key of an account whose plan does NOT include API access does not authenticate, and the call returns 401. Remove the `Authorization` header to use the free anonymous tier instead. Quota headers: `X-RateLimit-Limit`, `X-RateLimit-Used`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time of the next UTC midnight). `Retry-After` is set on 429 and 503. A 502 or 503 answer gives the consumed quota back, and so does a 429 FREE_CAPACITY_REACHED and a 200 reused answer; SERVICE_UNAVAILABLE consumes none. **Request format.** Send the body as JSON with `Content-Type: application/json`: any other content type returns 415. Without an `Authorization` header, a request sent by a web page of another site (an `Origin` other than the SERPmantics app, or `Sec-Fetch-Site: cross-site`) returns 403. Server-to-server calls send no `Origin` header and are not affected.

  shallow
• create_score

  Analyze content optimization score Analyzes the optimization score of the provided content for a specific guide

  shallow
• delete_guide

  Delete a guide Deletes a specific guide

  shallow
• delete_guides

  Delete multiple guides Deletes multiple guides at once

  shallow
• delete_intent

  Delete generated intent analysis for a guide Removes previously generated intent analysis for the given guide.

  shallow
• delete_internal_links

  Delete generated internal-links suggestions for a guide Removes previously generated internal-links suggestions for the given guide.

  shallow
• delete_meta

  Delete generated meta for a guide Removes previously generated meta titles/descriptions for the given guide.

  shallow
• delete_outline

  Delete generated outline for a guide Removes previously generated outline data for the given guide.

  shallow
• discover_persona_brief_pages

  Find the representative pages of a website from its sitemaps, before generating a persona brief (free tool) Reads the sitemaps of a website (declared in robots.txt, otherwise /sitemap.xml, /sitemap_index.xml and /wp-sitemap.xml) and returns up to 200 URLs of the same host, editorial pages first. The first URLs, as many as the URL limit of your tier, are flagged `suggested`: send them in `urls` to `POST /api/v1/tools/persona-brief`. Same tiers as the creation call, with their own daily counter per UTC day: 20 discoveries per day per IP address without an API key, 50 for a signed-in account, 200 with the API key of an account whose plan includes API access. A key whose plan does not include API access returns 401: remove the `Authorization` header to use the free anonymous tier. Quota headers: `X-RateLimit-Limit`, `X-RateLimit-Used`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. `Retry-After` is set on 429 and 503. A 400, 502 or 503 answer gives the consumed quota back; SERVICE_UNAVAILABLE consumes none. **Request format.** Send the body as JSON with `Content-Type: application/json`: any other content type returns 415. Without an `Authorization` header, a request sent by a web page of another site (an `Origin` other than the SERPmantics app, or `Sec-Fetch-Site: cross-site`) returns 403. Server-to-server calls send no `Origin` header and are not affected.

  shallow
• get_aissistant_tokens

  Get the current user's available AI tokens Returns the number of AI tokens available to the authenticated user. These tokens fund EVERY AI feature in SERPmantics — meta, outline, intent, internal-links, EEAT, EEAT competitors, score, AND the AISSistant prompts. The endpoint lives under /aissistant for historical reasons but the balance is shared across all AI features. Do NOT confuse with guide-creation credits (see /api/v1/credits). For a combined view (credits + tokens) prefer /api/v1/credits.

  shallow
• get_citation_check

  Read an AI citation test, poll until it is done Returns the test started by `POST /api/v1/tools/citation-check`. While `status` is `pending` or `running`, call again every 3 seconds: each engine fills in as soon as it has answered. When `status` is `done`, at least one engine answered; `summary.citedBy` engines cite your domain out of `summary.enginesAnswered` engines that answered. When `status` is `failed`, `failureCode` says why (NO_ENGINE_ANSWERED, TIMEOUT, INTERNAL). Per engine: `cited` is true when a source of the answer is on your registrable domain or one of its subdomains, and `citedUrls` lists those pages; `mentioned` is true when your brand name appears in the answer text, which is NOT a citation. `status` no_answer means the engine showed no answer for this question (Google often shows no AI Overview), which is not a failure. No quota is consumed. The `checkId` is random: whoever holds it can read the test, which is what makes share links work. Tests expire after 30 days. Reads that are not attributed to an account are capped at 1000 per IP address and per UTC day, far above any legitimate polling: crossing it returns 429 READ_RATE_LIMITED with `Retry-After`.

  shallow
• get_credit_ledger

  Grand-livre crédits d'un compte (admin) Timeline complète et immuable des mouvements de crédits d'un utilisateur (octrois, consommations, refunds, resets, ajustements admin), avec libellés FR en clair, delta signé, solde après, source, auteur et référence. Inclut le solde reconstruit à une date arbitraire (paramètre `at`) et un contrôle de cohérence (solde == dernier balanceAfter == somme des deltas). Réservé aux administrateurs. Lecture seule.

  shallow
• get_credits

  Get user balance (guide credits + AI tokens) Returns the authenticated user's full balance. SERPmantics has TWO distinct currencies: - **credits** (`credits`): how many NEW GUIDES the user can still create. Consumed once per guide creation. `"unlimited"` if the user's plan grants unlimited guide creation (`hasUnlimitedCredits: true`). - **AI tokens** (`tokens`): pool consumed by every AI feature (meta, outline, intent, internal-links, EEAT, EEAT competitors…). Each feature has its own cost — call `/api/v1/tokens-usage` to get the per-feature pricing. Do not confuse the two: running out of `credits` blocks new guides; running out of `tokens` blocks AI features inside existing guides.

  shallow
• get_eeat

  Get E-E-A-T analysis results Retrieves the result of an E-E-A-T analysis. Either pass `eeatId` (returned by POST /api/v1/eeat) to fetch a specific analysis, or pass `guideId` to fetch the latest analysis for that guide. Poll this endpoint until `status` is `done` (results available) or `failed`.

  shallow
• get_eeat_competitors

  Get E-E-A-T analysis results for a guide's competitors Retrieves the E-E-A-T analysis results for the top competitors of a guide. Poll this endpoint until `pending` is `0` to know when the full analysis is complete. Individual competitor results are available as soon as their `status` is `done`.

  shallow
• get_guide

  Get data for a specific guide Retrieves details of a specific guide. While the guide is being created, the endpoint returns 202 (poll again later). If the creation failed permanently (explicit terminal flag, or a failure older than 15 minutes with no retry left, see progressStatus.terminalInferred), it returns 200 with success=false, status=failed, a human-readable French error message, creationFailed=true, refunded (whether the consumed credits were automatically given back) and guide.progressStatus (raw reason, message, terminal). Stop polling in that case.

  shallow
• get_guides

  List user's guides Returns a list of guides for the authenticated user

  shallow
• get_intent

  Get search intent analysis for a guide Retrieves existing intent analysis results for a guide

  shallow
• get_internal_links

  Get internal linking suggestions for a guide Retrieves existing internal linking suggestions for a guide

  shallow
• get_meta

  Get generated meta titles and descriptions for a guide Retrieves generated SEO meta titles and descriptions for a guide

  shallow
• get_outline

  Get generated page structure for a guide Retrieves the generated page structure (flat heading list) for a guide.

  shallow
• get_persona_brief

  Read an AI persona and brand voice brief, poll until it is done Returns the brief started by `POST /api/v1/tools/persona-brief`. While `status` is `pending`, `fetching`, `analyzing` or `synthesizing`, call again every 3 seconds: `progress` and `pages` show what has been read so far. When `status` is `done`, `brief` holds the structured brief, `brief.writingPrompt` the ready-to-paste prompt and `markdown` the full document. When `status` is `failed`, `failureReason` says why (NO_USABLE_PAGE, LLM_UNAVAILABLE, TIMEOUT, INTERNAL). A page with a `failureReason` did not contribute to the brief. ANALYSIS_FAILED is the only one on a page that was read: it keeps its `title` and `wordCount`, stays counted in `progress.pagesFetched` and never enters `progress.pagesAnalyzed` nor `metrics`. No quota is consumed. The `briefId` is random: whoever holds it can read the brief, which is what makes share links work. Briefs expire after 90 days. Reads that are not attributed to an account are subject to three anti-abuse counters, all per IP address and per UTC day: the total number of requests, the reads of a single brief, and the number of different briefs read. All three are far above any legitimate polling, including the busiest paid account: crossing any of them returns 429 READ_RATE_LIMITED with `Retry-After`. Once the cost ceiling is reached, further requests keep being refused until it resets, whether or not they carry a valid briefId.

  shallow
• get_tokens_usage

  Get API token usage costs for different endpoints Returns the number of tokens required for each API endpoint operation. Note: `eeatCompetitorsTokensCostPerCompetitor` is a **per-competitor** cost. The total cost of POST /api/v1/eeat-competitors equals this value × the number of competitors analyzed (deduplicated URLs in the guide's top-10 SERP, capped at 10).

  shallow
• get_usage

  Get current API usage and quota status Returns the current period's API guide usage, quota limit, remaining count and the renewal date. Aligned on the Stripe subscription billing cycle. Does not consume credits.

  shallow
• update_guide

  Update a guide Updates editable fields of a specific guide (group, status, share state, linked URL, meta, hidden expressions). Only owners may update.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/e5d85ba0-e544-4742-b08a-941548b79a16/badge.svg)](https://vouch.tools/servers/e5d85ba0-e544-4742-b08a-941548b79a16)