v1
Guide

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.

IMPORTANT, HOW TO READ THE RESPONSE OF THIS ENDPOINT, WHICH SPENDS CREDITS. Queries listed in guidesFailed are PROVEN not to have produced a guide and their credit was given back (unless the account has unlimited credits, where nothing was reserved): re-sending them is free and correct. Queries listed in guidesUnknown have an UNDECIDABLE outcome and their credit is deliberately KEPT, because the guide was most likely written: DO NOT re-send them, you would pay for the same guide twice. Look them up in GET /api/v1/guides after a few minutes instead, and contact support if nothing shows up. Finally, a 200 is NOT a promise that every query produced a guide: compare guides.length with the number of queries you sent, never read success alone, and never re-send a query just because it is missing from guides.

post/api/v1/guides

Request

  • Base URL: https://app.serpmantics.com (the document declares no server; this is the origin it was published from)
  • URL: https://app.serpmantics.com/api/v1/guides
  • Auth: HTTP bearer

Request body

queriesstring[] required

Array of queries to create guides for

langstring required

Language code for the guides

source'google' | 'google_ai_overview' | 'google_ai_overview_citations' | 'chatgpt' | 'chatgpt_citations' | 'perplexity' | 'perplexity_citations' | 'claude' | 'claude_citations' | 'gemini' | 'gemini_citations' | 'grok' | 'grok_citations' | 'mistral' | 'mistral_citations' | 'deepseek' | 'deepseek_citations'

Target engine AND analysis mode the guide optimizes for. One guide = one source. google analyzes the Google SERP (1 credit per guide). Google's AI answers have the same two modes as AI engines : google_ai_overview analyzes the TEXT of the AI answers (AI Overview, completed with AI Mode) ; google_ai_overview_citations analyzes the content of the web SOURCES those answers cite, the recommended mode for GEO. 1 credit per guide in both modes, same language/country parameters as google. 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.

Response

No requested query landed in guidesFailed nor in guidesUnknown. Returned with 206 instead as soon as one requested query landed in either list. WARNING, A 200 IS NOT A PROMISE THAT EVERY QUERY PRODUCED A GUIDE, AND THE CREDIT IS STILL SPENT. When the backend answers success WITHOUT a usable guide id, the query enters NONE of the three lists and its credit is KEPT on purpose (the guide was most likely written, so retrying would pay for it twice). A batch made only of such queries therefore answers 200 { success: true, guides: [], guidesFailed: [], guidesUnknown: [] } with the credits debited. Always compare guides.length with the number of queries you sent, never read success alone; on a difference, look the guides up in GET /api/v1/guides instead of re-sending the query.

successboolean

true only when BOTH guidesFailed and guidesUnknown are empty. An undecidable outcome is not a success: its credit was kept, so reporting it as a complete success would hide a charge with nothing to show yet. WARNING, true still does not mean that every query produced a guide: a query answered as a success WITHOUT a usable guide id enters neither list, so success stays true while guides can be shorter than the queries you sent, credit spent. guides.length is the only reliable count of what was created.

creditsnumber nullable

Spendable balance (plan credits plus non-expired One-Shot) re-read from the source AFTER every movement. null when that read failed: the guides were still created and charged, the balance is simply unknown. Never a locally estimated figure, which would silently open or close the creation path.

hasUnlimitedCreditsboolean

Whether the account spends from an unlimited plan. Reported on the same response as credits because it decides what a client may TRUTHFULLY say about money: credits are only reserved when this is false, so a message claiming a charge is wrong on an unlimited account, and omitting it hides a real charge on every other one. Read it from here rather than from a value cached when the page was loaded.

guidesCountBeforeinteger nullable

Number of guides the user owned BEFORE this call (0 for a first guide). null when the count could not be read.

Changes

No recorded changes to this operation across all 1 revision of this API.