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