# Geoptie Docs

> Read and manage your AI-search visibility data: the REST API, and the MCP server that lets an AI assistant use it. Visibility across engines, the prompts you track, citations, competitors, recommendations and content.

- [Introduction](https://geoptie.com/docs/index.md): Read and manage your AI-search visibility data over HTTP.
- [Quickstart](https://geoptie.com/docs/quickstart.md): Create a key, validate it, and make your first request.
- [Authentication](https://geoptie.com/docs/authentication.md): Key types, how to send them, and how access is checked.
- [Pagination and dates](https://geoptie.com/docs/pagination.md): Walk large result sets, and filter them by date.
- [Long-running operations](https://geoptie.com/docs/long-running.md): Start work that takes minutes, and poll for the result.
- [Rate limits](https://geoptie.com/docs/rate-limits.md): How many requests you can make, and how to stay within them.
- [Errors](https://geoptie.com/docs/errors.md): The error format, every code the API returns, and when to retry.
- [List brands](https://geoptie.com/docs/api-reference/brands/list-brands.md): Every brand this key can reach, with the engines and country each is measured on.
- [Create a brand](https://geoptie.com/docs/api-reference/brands/create-a-brand.md): Add a brand to start measuring. Returns the brand as created, including the engines it will be tracked on.
- [Get a brand](https://geoptie.com/docs/api-reference/brands/get-a-brand.md): One brand's settings: name, domain, aliases, engines and country.
- [Brand visibility](https://geoptie.com/docs/api-reference/visibility/brand-visibility.md): How often and how prominently this brand appears in engine answers, day by day, with a summary for the window. Narrow it to one engine, a topic, or a single prompt.
- [List a brand's prompts](https://geoptie.com/docs/api-reference/prompts/list-a-brands-prompts.md): The prompts being measured for this brand. Add `include=metrics` for each prompt's visibility over a window.
- [Start tracking prompts](https://geoptie.com/docs/api-reference/prompts/start-tracking-prompts.md): Start measuring one or more prompts for this brand. Prompts already being tracked are left unchanged, and the response reports how many were added.
- [Stop tracking a prompt](https://geoptie.com/docs/api-reference/prompts/stop-tracking-a-prompt.md): Stop measuring a prompt for this brand. It will not be run again.
- [Assign or clear a prompt's topic](https://geoptie.com/docs/api-reference/prompts/assign-or-clear-a-prompts-topic.md): File a prompt under a topic, or clear its topic by sending null.
- [Get a prompt](https://geoptie.com/docs/api-reference/prompts/get-a-prompt.md): One prompt: its text, the country it is measured in, when it last ran, and each of your brands' subscription to it with its topic and status. 404 if none of your brands tracks it.
- [Answers for a prompt](https://geoptie.com/docs/api-reference/prompts/answers-for-a-prompt.md): The full answer each engine gave for this prompt, day by day, as the text a user would have seen. Add `include` to expand each answer with the sources it cited and the brands it named, both of which belong to one answer rather than to the prompt as a whole.
- [Brands mentioned in a prompt's answers](https://geoptie.com/docs/api-reference/prompts/brands-mentioned-in-a-prompts-answers.md): Every brand named in an answer to this prompt, including brands that are not yours, so you can see who the engines bring up. Each mention carries the `response_id` of the answer it was found in, which matches the `id` of a row from the answers endpoint.
- [List topics](https://geoptie.com/docs/api-reference/topics/list-topics.md): The topics defined for this brand. Topics group prompts so visibility can be read by theme.
- [Create a topic](https://geoptie.com/docs/api-reference/topics/create-a-topic.md): Create a topic to group this brand's prompts under.
- [Delete a topic](https://geoptie.com/docs/api-reference/topics/delete-a-topic.md): Delete a topic. Prompts filed under it stay tracked and become unfiled.
- [Rename a topic](https://geoptie.com/docs/api-reference/topics/rename-a-topic.md): Change a topic's name. The prompts filed under it are unaffected.
- [Citations for a brand](https://geoptie.com/docs/api-reference/citations/citations-for-a-brand.md): The complete raw citation feed for a brand: one row per prompt per day per page, newest day first, cursor-paginated with no ceiling. This is the endpoint for a full export into your own store.
- [Most-cited domains](https://geoptie.com/docs/api-reference/citations/most-cited-domains.md): The domains engines cite most when answering this brand's prompts, aggregated over the window and ranked by citation count. Top-N rather than paginated: `total_count` is how many domains matched and `capped` is true when there are more than this response carries.
- [Most-cited pages](https://geoptie.com/docs/api-reference/citations/most-cited-pages.md): The individual pages engines cite most when answering this brand's prompts, aggregated over the window and ranked by citation count. Top-N rather than paginated: check `capped` before treating the response as the complete set.
- [Citation trend for one domain or page](https://geoptie.com/docs/api-reference/citations/citation-trend-for-one-domain-or-page.md): Daily citation counts for a single target, with the brand's total for the same days so you get share as well as volume. Pass `url` for one exact page, `domain` for a root domain (subdomains roll up), or neither to get the brand's own domain, i.e. how often engines cite you. Days the brand did not ru…
- [Your brand versus its competitors](https://geoptie.com/docs/api-reference/competitors/your-brand-versus-its-competitors.md): Which other brands appear alongside yours in the same answers, and your share of voice against them.
- [List recommendations](https://geoptie.com/docs/api-reference/recommendations/list-recommendations.md): Suggested actions for improving this brand's visibility, with the state of each.
- [Generate recommendations](https://geoptie.com/docs/api-reference/recommendations/generate-recommendations.md): Produce a fresh set of suggested actions for this brand, based on its current visibility and the content on its site.
- [Delete a recommendation](https://geoptie.com/docs/api-reference/recommendations/delete-a-recommendation.md): Remove a recommendation from the list.
- [Complete, dismiss or restore](https://geoptie.com/docs/api-reference/recommendations/complete-dismiss-or-restore.md): Mark a recommendation as done or dismissed, or put it back to open.
- [List audit reports](https://geoptie.com/docs/api-reference/audit-reports/list-audit-reports.md): Audit reports run for this workspace, newest first.
- [Run an audit](https://geoptie.com/docs/api-reference/audit-reports/run-an-audit.md): Audit a single URL for AI search. Returns straight away with an id and a `poll` path; the report is ready when its status is `complete`, usually within a minute or two.
- [Get an audit report](https://geoptie.com/docs/api-reference/audit-reports/get-an-audit-report.md): One audit report, with its score and findings once its status is `complete`.
- [Delete an audit report](https://geoptie.com/docs/api-reference/audit-reports/delete-an-audit-report.md): Remove an audit report and its findings.
- [List generations](https://geoptie.com/docs/api-reference/content-generations/list-generations.md): Articles this brand has generated, newest first. Rows are summary fields only: `brief_md`, `draft_md`, `slug` and the meta fields are omitted here and returned by a single fetch.
- [Generate a brief](https://geoptie.com/docs/api-reference/content-generations/generate-a-brief.md): Start a new article by researching it. This studies the pages engines already cite for the prompts you name and writes a brief from them; it does not write the article, which is the next step.
- [Get a generation](https://geoptie.com/docs/api-reference/content-generations/get-a-generation.md): One content project, including its brief and draft if they exist.
- [Delete a generation](https://geoptie.com/docs/api-reference/content-generations/delete-a-generation.md): Remove a content project along with its brief and draft.
- [Update a generation](https://geoptie.com/docs/api-reference/content-generations/update-a-generation.md): Change a generation's title, topic, slug, meta fields or brief.
- [Write the article from its brief](https://geoptie.com/docs/api-reference/content-generations/write-the-article-from-its-brief.md): Turn this generation's brief into the finished article. Call it once `status` is `brief_ready`.
- [List optimizations](https://geoptie.com/docs/api-reference/content-optimizations/list-optimizations.md): Pages analysed for this brand, with the score each received.
- [Analyse a page or pasted content](https://geoptie.com/docs/api-reference/content-optimizations/analyse-a-page-or-pasted-content.md): Score a page for AI search and get specific fixes for it. Pass a `url` to fetch, or paste at least 100 characters of `content`.
- [Get an optimization](https://geoptie.com/docs/api-reference/content-optimizations/get-an-optimization.md): One analysis, with its score and the fixes suggested for that page.
- [Delete an optimization](https://geoptie.com/docs/api-reference/content-optimizations/delete-an-optimization.md): Remove an analysis and its suggested fixes.
- [Re-score an optimization](https://geoptie.com/docs/api-reference/content-optimizations/re-score-an-optimization.md): Run the analysis again on the same page and update its score.
- [Introduction](https://geoptie.com/docs/mcp/introduction.md): Use Geoptie from Claude Code, Cursor, Codex and other AI assistants.
- [Setup](https://geoptie.com/docs/mcp/setup.md): Connect Claude Code, Cursor, Codex or any other MCP client.
- [Tools](https://geoptie.com/docs/mcp/tools.md): Every tool the Geoptie MCP server exposes, grouped by what it works on.
- [Recipes](https://geoptie.com/docs/mcp/recipes.md): Questions to ask, the tools behind them, and how to read the answer.

## OpenAPI Specs

- [openapi](/docs/openapi.json)