Skip to content
MentionBird.ai
Browse the documentation

MentionBird.ai API

Read how AI assistants talk about your brand — visibility, share of voice, the pages they cite, and the searches they run — and manage the brands, prompts, competitors and tags you track.

Get started

  1. Create an API key in your workspace settings.
  2. Send it as a bearer token on every request. See Authentication.
  3. Call List Tracked Brands first — most endpoints take a brand name exactly as it returns it.

Base URL https://api.mentionbird.ai/api/v1

Using this API with an AI assistant

The full OpenAPI 3.0 description lives at openapi.json. Point a ChatGPT Custom GPT Action or a Gemini Extension at that URL and every endpoint below becomes available to it.

If your client speaks MCP instead, add https://mcp.mentionbird.ai/mcp to it and sign in with your MentionBird.ai account, or connect with the same API key. See Authentication.

Building in n8n? Install MentionBird.ai's verified node for workflows, triggers and AI Agents, or connect an AI Agent through the MCP Client Tool. Both take an API key. See n8n.

Discovery

Find the brands, competitors, prompts, tags and AI platforms this workspace tracks. Start here — most other endpoints take a brand name or prompt ID returned by these.

Visibility

How often the brand appears in AI answers, and who it shares those answers with.

Citations

The pages and domains AI platforms cite when they answer, and how much of that is your own.

Searches

The web searches the AI platforms actually ran while answering a prompt.

Prompts

Per-prompt standings and the advice agent's guidance on improving them.

Answers

The raw AI answers behind every metric, in full.

Video

Summaries of cited YouTube videos the brand has paid to analyze.

Writes

Change what the workspace tracks: its brands, prompts, tags, competitors, aliases and owned domains. These need a write-enabled API key.

POST Add Tracked Brand Start tracking a new brand. Requires a write-enabled API key. /brands/tracked POST Create a Tag Create a prompt tag. When the brand already has a tag with the same slug, that tag comes back unchanged. Requires a write-enabled API key. /queries/tags POST Add Competitors Track competitors for a brand, up to the plan's per-brand limit (see getAccount). Requires a write-enabled API key. /brands/competitors POST Add Aliases Count extra spellings as the brand, or as a competitor, when an answer names them. Requires a write-enabled API key. /brands/aliases POST Start Ranking Advice Start a ranking-advice run for one prompt, spending credits: the price getAccount lists under agents.ranking_advice, charged when the run starts and refunded if it fails. The run takes 5-12 minutes, so this answers at once with run_id and status; read the advice with getRankingAdvice once status is done. A finished run whose sources haven't changed comes back free, as does a run already in progress, and an account that can't pay gets error_code insufficient_credits; none of these starts a run or charges anything. started is true only when this call started one, and credits is what it spends. Requires a write-enabled API key. /ranking-advice/runs POST Summarize a YouTube Video Summarize a YouTube video the brand's answers cite, spending credits: 1 per 5 minutes of video, rounded up, at most 24, charged when the run starts and refunded if it fails. The run usually takes about a minute, so this answers at once with run_id and status; read the result with getYouTubeSummary. A video the brand already has a summary of comes back free, as does a run in progress. A video that can't be summarized, or an account that can't pay, comes back with status error and an error_code; none of these starts a run or charges anything. started is true only when this call started one, and credits is what it spends. Requires a write-enabled API key. /youtube/summaries POST Archive Prompts Stop running prompts on every AI platform. Their results stay in the charts, and restorePrompts brings them back. Requires a write-enabled API key. /prompts/archive POST Restore Prompts Run archived prompts again on the AI platforms they were removed from, as far as the plan's prompt runs allow. A restored prompt is checked within the hour. Requires a write-enabled API key. /prompts/restore POST Change Prompts' AI Platforms Add or remove AI platforms on prompts. Removals apply first, so the prompt runs they free count toward the additions in the same call. In a workspace already over its prompt-run limit, a note says how many added pairs won't run until runs free up. Requires a write-enabled API key. /prompts/llms POST Tag or Untag Prompts Add tags to prompts or remove them. An added tag that doesn't exist yet is created. Requires a write-enabled API key. /prompts/tags POST Check a Brand Now Queue the brand's prompts to run at the next scheduler tick, within 15 minutes. Prompts already checked in the current cadence period (today since 00:00 UTC on a daily brand, otherwise the last cadence_days) are skipped. Asking again in the same period re-runs only prompts whose check failed. The brand's regular schedule doesn't move. Requires a write-enabled API key. /brands/check-now POST Stop Tracking a Brand Stop tracking a brand. Its history is kept, and addTrackedBrand with the same name tracks it again. The workspace's last brand can't be archived. Requires a write-enabled API key. /brands/archive POST Remove Competitors Permanently remove competitors. Each one's aliases and owned domains are deleted with it, and this can't be undone. Requires a write-enabled API key. /brands/competitors/remove POST Remove Aliases Permanently remove aliases from the brand or one of its competitors. This can't be undone. Requires a write-enabled API key. /brands/aliases/remove POST Add Owned Domains Declare domains as the brand's own, or a competitor's. Citations of them are then labelled yours or competitor:<name> instead of earned. Requires a write-enabled API key. /brands/owned-domains POST Remove Owned Domains Permanently remove declared domains from the brand or one of its competitors. Their citations read as earned again. Requires a write-enabled API key. /brands/owned-domains/remove POST Rename or Recolor a Tag Rename a prompt tag or change its color. The prompts carrying it keep it, and its slug follows the new name. Requires a write-enabled API key. /queries/tags/update POST Delete a Tag Permanently delete a prompt tag. The prompts that carried it stay tracked and lose only the tag. Requires a write-enabled API key. /queries/tags/delete POST Add Prompts to Track Add prompts to track for a brand across the chosen AI platforms and queue the first crawl. Requires a write-enabled API key. /prompts