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
- Create an API key in your workspace settings.
- Send it as a bearer token on every request. See Authentication.
- 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.
/brands/tracked
GET
List Tracked Prompts
List the prompts tracked for a brand, with their search-volume and difficulty buckets and the prompt ID token other endpoints need.
/queries
GET
List Prompt Tags
List the tags this workspace has assigned to a brand's prompts. Pass a tag's slug as `query_tag` on other endpoints.
/queries/tags
GET
List AI Platforms
List the AI platforms available to this workspace (ChatGPT, Claude, Gemini, Perplexity, Grok) and the models behind them.
/llm-providers
GET
List Competitors
List the competitors tracked for a brand, with each one's domain. getTopMentionedBrands marks their rows is_tracked_competitor.
/brands/competitors
GET
List Brand Aliases
List the extra spellings that count as the brand, or as one of its competitors, when an answer names them.
/brands/aliases
GET
Get Plan and Usage
Show the workspace's plan, credit balance, how much of each limit is used, the AI platforms the plan allows, and each paid agent's price. Call it before adding prompts, competitors or brands, or spending credits.
/account
Visibility
How often the brand appears in AI answers, and who it shares those answers with.
/visibility
GET
Get Share of Voice
The brands named most often across this brand's tracked prompts — who you are losing to, and by how much.
/brands/top-mentioned
Citations
The pages and domains AI platforms cite when they answer, and how much of that is your own.
/citations/domains
GET
List Citations
Individual cited URLs with page metadata, for detailed source analysis.
/citations
GET
List Citation Taxonomy
The valid source_type and content_type values to pass to the citation endpoints. source_type describes the kind of site, content_type the kind of page.
/citations/tags
GET
Get Citation Breakdown
The kinds of sources AI platforms cite when answering this brand's prompts: those citations grouped by source_type (kind of site), content_type (kind of page) or url_status (link health).
/citations/breakdown
GET
Get Owned vs Earned Share
How citations split between domains the brand owns, competitor-owned domains and earned third-party coverage. The filters narrow it the way the dashboard's sources page does.
/sources/owned-share
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.
/prompts/leaderboard
GET
List Prompts by Visibility
Prompts ordered by visibility: ascending finds the gaps where the brand loses, descending finds the wins.
/prompts/by-visibility
GET
Get Ranking Advice for a Prompt
Completed ranking-advice runs for ONE prompt — what to change to rank better. Read-only: this never starts a new run. Requires brand_prompt_id from listQueries.
/prompts/ranking-advice
GET
List Ranking Advice Runs
Ranking-advice runs across ALL of a brand's prompts. Use this to find which prompts already have advice before calling getRankingAdvice.
/ranking-advice
Answers
The raw AI answers behind every metric, in full.
/query-runs
GET
Get One AI Answer in Full
One run in full: the complete answer text, every brand mentioned, every source cited and every web search the AI ran. Use this after listQueryRuns when the preview isn't enough.
/query-runs/{run_id}
Video
Summaries of cited YouTube videos the brand has paid to analyze.
/youtube/summaries
GET
Get YouTube Summary
Summary, key points and optional transcript for one cited YouTube URL. A brand whose run hasn't finished gets a 404 whose details carry its run_id, status and error_code.
/youtube/summary
Writes
Change what the workspace tracks: its brands, prompts, tags, competitors, aliases and owned domains. These need 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