# 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. To rank the pages or domains cited for a p…
- [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. Narrow it to a topic or to specific…
- [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. Pass `prompt_id` to get the pages cited for one prompt, without paging th…
- [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. Every row says whether it is in the brand's tracked set; pass `tracked=true` for just that set, which is the list share of voice is computed over, zero-mention competitors included.
- [Tracked competitors over time](https://geoptie.com/docs/api-reference/competitors/tracked-competitors-over-time.md): Daily or weekly series for the brand and each tracked competitor: visibility, share of voice, mentions, position, sentiment, win rate and citations of their own website, over the brand's tracked prompts. Read from precomputed daily rows, so it is cheap at any window length. A competitor tracked rece…
- [One tracked competitor in detail](https://geoptie.com/docs/api-reference/competitors/one-tracked-competitor-in-detail.md): A tracked competitor against your brand: totals for the window and for the window of the same length before it, plus one breakdown by engine, topic or prompt. The same numbers as the competitor view in the dashboard.
- [List tracked competitors](https://geoptie.com/docs/api-reference/competitors/list-tracked-competitors.md): The competitors this brand has chosen to compete against. This is the set share of voice and trends are computed over.
- [Track competitors](https://geoptie.com/docs/api-reference/competitors/track-competitors.md): Add up to 50 competitors to the tracked set. Each needs a name and a website; other spellings can be given as aliases. A name the answers have never mentioned is fine: it joins share of voice at zero. A name already tracked is refreshed in place, a name on the ignore list is tracked again. History f…
- [Untrack a competitor](https://geoptie.com/docs/api-reference/competitors/untrack-a-competitor.md): Remove a competitor from the tracked set. Its mentions are kept and it returns to the discovered list, from where it can be tracked again or ignored.
- [Edit a tracked competitor](https://geoptie.com/docs/api-reference/competitors/edit-a-tracked-competitor.md): Change the name, website or aliases. Any change to the definition re-attributes past mentions and recomputes the competitor's history in the background; the response says whether that was triggered.
- [List ignored competitors](https://geoptie.com/docs/api-reference/competitors/list-ignored-competitors.md): Discovered names this brand has hidden from the Competitors page. Ignored names are left out of share of voice.
- [Ignore competitors](https://geoptie.com/docs/api-reference/competitors/ignore-competitors.md): Hide up to 50 discovered names. A tracked competitor cannot be ignored: untrack it first, then ignore it; such names are reported in `skipped`.
- [Stop ignoring a competitor](https://geoptie.com/docs/api-reference/competitors/stop-ignoring-a-competitor.md): Remove a name from the ignore list. It shows on the discovered list again.
- [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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.