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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, score…). 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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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`.

Parameters1

guideId

string

required

ID of the guide whose competitors should be returned

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide whose competitors should be returned"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

guideId

string

required

ID of the guide whose competitors should be analyzed

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide whose competitors should be analyzed"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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`.

Parameters2

eeatId	string	optional	ID of a specific analysis (returned by POST /api/v1/eeat). Either `eeatId` or `guideId` must be provided.
guideId	string	optional	ID of the guide whose latest analysis should be returned. Either `eeatId` or `guideId` must be provided.

Raw schema

{
  "type": "object",
  "properties": {
    "eeatId": {
      "type": "string",
      "description": "ID of a specific analysis (returned by POST /api/v1/eeat). Either `eeatId` or `guideId` must be provided."
    },
    "guideId": {
      "type": "string",
      "description": "ID of the guide whose latest analysis should be returned. Either `eeatId` or `guideId` must be provided."
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters2

guideId	string	required	ID of the guide to analyze
html_content	string	required	HTML of the article to analyze (without `<mark>` tags)

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide to analyze"
    },
    "html_content": {
      "type": "string",
      "description": "HTML of the article to analyze (without `<mark>` tags)"
    }
  },
  "required": [
    "guideId",
    "html_content"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_intent

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters2

guideId	string	required	ID of the guide
content	string	optional	Optional content to analyze against the intent (only after intent analysis was created)

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    },
    "content": {
      "type": "string",
      "description": "Optional content to analyze against the intent (only after intent analysis was created)"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_intent

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_internal_links

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_internal_links

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_meta

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_meta

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_outline

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_outline

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

Parameters1

guideId

string

required

ID of the guide

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide"
    }
  },
  "required": [
    "guideId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

userId	string	required	Identifiant Mongo de l'utilisateur.
at	string	optional	Date ISO pour reconstruire le solde à cet instant (point-in-time).
limit	number	optional	Nombre maximum de lignes (défaut 200, max 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "Identifiant Mongo de l'utilisateur."
    },
    "at": {
      "type": "string",
      "description": "Date ISO pour reconstruire le solde à cet instant (point-in-time)."
    },
    "limit": {
      "type": "number",
      "description": "Nombre maximum de lignes (défaut 200, max 1000)."
    }
  },
  "required": [
    "userId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_guide

Get data for a specific guide Retrieves details of a specific guide

Parameters1

id

string

required

The ID of the guide to retrieve

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the guide to retrieve"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters7

id	string	required	The ID of the guide to update
group	string	optional	Group/folder the guide belongs to (triggers cannibalisation analysis on previous and new group)
status	string	optional	Editorial status of the guide. Empty string clears the status.
shareState	string	optional	Sharing mode. Plan must allow shared-read or shared-edit, otherwise 403 is returned.
linkedUrl	string	optional	Public URL where the guide content is published (validated as URL)
meta	object	optional	SEO meta override for the guide
hiddenExpressions	array	optional	Expressions to hide from the optimisation suggestions

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the guide to update"
    },
    "group": {
      "type": "string",
      "description": "Group/folder the guide belongs to (triggers cannibalisation analysis on previous and new group)"
    },
    "status": {
      "type": "string",
      "enum": [
        "",
        "draft",
        "active",
        "review",
        "published",
        "archived"
      ],
      "description": "Editorial status of the guide. Empty string clears the status."
    },
    "shareState": {
      "type": "string",
      "enum": [
        "private",
        "shared-read",
        "shared-edit"
      ],
      "description": "Sharing mode. Plan must allow shared-read or shared-edit, otherwise 403 is returned."
    },
    "linkedUrl": {
      "type": "string",
      "description": "Public URL where the guide content is published (validated as URL)"
    },
    "meta": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      },
      "additionalProperties": {},
      "description": "SEO meta override for the guide"
    },
    "hiddenExpressions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Expressions to hide from the optimisation suggestions"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_guide

Delete a guide Deletes a specific guide

Parameters1

id

string

required

The ID of the guide to delete

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the guide to delete"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_guides

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

Parameters2

page	any	optional	Page number for pagination
pageSize	any	optional	Number of guides per page

Raw schema

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number for pagination"
    },
    "pageSize": {
      "description": "Number of guides per page"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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"} 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.

Parameters3

queries	array	required	Array of queries to create guides for
lang	string	required	Language code for the guides
source	string	optional	Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`.

Raw schema

{
  "type": "object",
  "properties": {
    "queries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of queries to create guides for"
    },
    "lang": {
      "type": "string",
      "description": "Language code for the guides"
    },
    "source": {
      "type": "string",
      "enum": [
        "google",
        "chatgpt",
        "chatgpt_citations",
        "perplexity",
        "perplexity_citations",
        "claude",
        "claude_citations",
        "gemini",
        "gemini_citations",
        "grok",
        "grok_citations",
        "mistral",
        "mistral_citations",
        "deepseek",
        "deepseek_citations"
      ],
      "description": "Target engine AND analysis mode the guide optimizes for. One guide = one source. `google` analyzes the Google SERP (1 credit per guide). For AI engines (chatgpt, perplexity, claude, gemini, grok, mistral, deepseek), pick the mode: `<engine>` analyzes the AI's generated ANSWER for the query; `<engine>_citations` analyzes the content of the web SOURCES the AI cites, which is the recommended mode for GEO (become one of the cited sources). Both AI modes cost 4 credits per guide. Omit for the default `google`."
    }
  },
  "required": [
    "queries",
    "lang"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_guides

Delete multiple guides Deletes multiple guides at once

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_score

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

Parameters3

guideId	string	required	ID of the guide to analyze
content	string	required	Content to analyze
saveToGuide	boolean	optional	Whether to save the content and the analysis score back to the guide (default: true)

Raw schema

{
  "type": "object",
  "properties": {
    "guideId": {
      "type": "string",
      "description": "ID of the guide to analyze"
    },
    "content": {
      "type": "string",
      "description": "Content to analyze"
    },
    "saveToGuide": {
      "type": "boolean",
      "description": "Whether to save the content and the analysis score back to the guide (default: true)\n"
    }
  },
  "required": [
    "guideId",
    "content"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Serpmantics

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

get_aissistant_tokens

get_credits

get_eeat_competitors

create_eeat_competitors

get_eeat

create_eeat

get_intent

create_intent

delete_intent

get_internal_links

create_internal_links

delete_internal_links

get_meta

create_meta

delete_meta

get_outline

create_outline

delete_outline

get_tokens_usage

get_usage

get_credit_ledger

get_guide

update_guide

delete_guide

get_guides

create_guides

delete_guides

create_score

Install

Remote endpoint