API Changelog

Public, dated list of API changes. Breaking changes are called out explicitly. Deprecations get 90 days notice before removal.

How we version

  • The API is versioned as v1 in the path (e.g. POST /v1/ask).
  • Non-breaking changes — new endpoints, new optional request params, new response fields, new error codes — ship continuously without a version bump. Clients should ignore unknown response fields.
  • Breaking changes trigger a new version path (v2). The previous version stays live for at least 12 months.

2026-07-03 — Pricing v2: subscription plans

The credit wallet moves to subscription plans. Credits still debit per call from a prepaid balance; plans are how the credits land.

  • PricingSubscription plans — Monthly at $5/mo (1,000 credits per month) or Annual at $54/yr (12,000 credits granted up front each year).
  • Added300 free credits on signup — a one-time grant on account creation, no card required.
  • PricingTop-up packs for paid plans — 1k–100k credits at $4.00 per 1k (monthly) or $3.00 per 1k (annual).

2026-06-10 — Remote MCP connector

MentionsAPI is now callable as native tools from any MCP-compatible client.

  • AddedHosted remote MCP server at https://api.mentionsapi.com/mcp with OAuth — add it as a custom connector in claude.ai or Claude Desktop with no install and no key copying. Connecting mints an API key named “Claude” that you can revoke from the dashboard anytime.
  • AddedThe same URL works in any Streamable-HTTP MCP client with an Authorization: Bearer header.
  • AddedFour tools exposed: mentions_check, mentions_watch, mentions_discover, and mentions_compare.

2026-06 — Endpoint suite, recipes, and health

Rolled out across June alongside the MCP connector.

  • AddedPOST /v1/discover (165 credits) — generate up to 50 query candidates that real users ask about a brand, each scored 0–1 and tagged with intent (informational, commercial, comparison, transactional).
  • AddedPOST /v1/compare (500 credits) — head-to-head comparison of two brands or two queries across all 4 LLM APIs, with a normalized delta_pct and a winner.
  • Added/v1/watch CRUD (free; each scheduled run billed at the configured mode’s credit rate) — recurring checks that fire an HMAC-SHA256-signed webhook (x-mentionsapi-signature) on triggers like rank_changed and mention_added, with a full delta payload.
  • AddedGET /v1/health (free, unauthenticated) — 7-day rolling success rate and p95 latency per platform, KV-cached 60s.
  • ChangedGET /v1/usage — now returns per-endpoint, per-provider, and per-mode cost breakdowns plus a bucketed time series. Still free.
  • AddedRecipes section — nine copy-paste guides in curl, Node, and Python: track brands across surfaces, daily brand monitor, competitive share of voice, find citation sources, discover target queries, GEO dashboard, LLM eval suite, rank-drop alerts, and AI Overview monitoring.
  • AddedLocal MCP server via npx @mentionsapi/mcp, with editor setup guides for Claude Code, Cursor, Windsurf, and ChatGPT Plus.

2026-04-25 — v1.0 Launch

Initial public release. One brand-visibility check API across every AI search surface — the 4 LLM APIs (ChatGPT, Claude, Gemini, Perplexity) plus live UI scrapes of Perplexity, ChatGPT, Gemini, Google AI Overview, Google AI Mode, and Bing Copilot — with brand-mention extraction, citation canonicalization, and prepaid credit billing.

Added

  • AddedPOST /v1/check — primary endpoint. One query + one brand in, per-platform mention / rank / citations out. Eight modes: quick (4 LLM APIs in parallel), perplexity_live, chatgpt_live, gemini_live, ai_overview, ai_mode, bing_copilot, and all_live (single-call bundle of all 6 live surfaces). Partial-failure refunds on every mode that fans out across platforms.
  • AddedPOST /v1/ask — legacy raw-query path. Supports prompt or messages, per-provider model pinning, json_schema structured output, web search, brand extraction, and partial-success semantics.
  • AddedGET /v1/ask/:id — 30-day retrieval of archived responses.
  • AddedPOST /v1/extract_brands — run brand extraction on arbitrary text (no LLM round-trip).
  • AddedGET /v1/mentions/search (35 credits flat) — query the crawler-populated brand-mentions database.
  • AddedPOST /v1/mentions/crawl (650 credits flat) — on-demand 4-provider crawl with web_search on; results indexed into the mentions DB.
  • AddedGET /v1/usage — usage events over an arbitrary window, grouped by day/hour/total.
  • Added/v1/keys CRUD — mint, list, and revoke API keys (session-authenticated via dashboard login).
  • Added/v1/webhooks CRUD — register and rotate webhook endpoints for async ask.completed deliveries.
  • Added/v1/monitors CRUD — schedule recurring prompt runs; the hourly cron executes due monitors and can fire an ask.completed webhook per run.
  • AddedStandard (async) mode on POST /v1/ask with a 15-minute SLA and a 30% discount versus live. Poll with GET /v1/ask/:id or receive a signed webhook on completion.
  • AddedSigned webhook deliveries — HMAC-SHA256 over the raw body, timestamp check, exponential-backoff retries with a DLQ.
  • Added3-tier cache (Cloudflare Cache API → KV → Postgres) on /v1/ask. Hits return at the cached price (5 credits); served tier is reported as cache_tier in the response.
  • AddedOpenAPI 3.1 spec at GET /openapi.json (generated from the live Zod schemas) and interactive Swagger UI at /docs/explorer.
  • AddedOfficial SDKs — @mentionsapi/sdk (TypeScript/Node) and a Python SDK.

Security

  • SecurityEdge Function broker pattern — the Cloudflare Worker holds zero LLM provider keys. Every upstream call flows through a per-provider Supabase Edge Function that enforces a model allowlist and hard-denies image / audio / video / embedding models.
  • SecurityAPI keys carry 256 bits of entropy from crypto.getRandomValues() and are stored as SHA-256 hashes; only the 12-char prefix is retrievable.
  • SecurityRow-Level Security is enabled on all dashboard-accessed tables. The Worker uses the service role to bypass; the frontend reads via user JWT only.
  • SecurityProvider proxies scrub API-key patterns from every log and error response and cap prompt length at 20 KB.

Pricing

  • Pricing/v1/check mode:quick — 130 credits per call (5 on cache hits).
  • Pricing/v1/check live surface modes — 15–85 credits per call (ai_overview and bing_copilot 15; chatgpt_live, gemini_live, and ai_mode 35; perplexity_live 85).
  • Pricing/v1/check mode:all_live — 165 credits per call; if k of 6 surfaces succeed you pay (k/6) × 165.
  • Pricing/v1/ask cache hit (any tier) — 5 credits per call.
  • Pricing/v1/ask single provider, no web search — 15 credits per call.
  • Pricing/v1/ask single provider, with web search — 60 credits per call.
  • Pricing/v1/ask multi-provider (2–4), no web search — 75 credits per call.
  • Pricing/v1/ask multi-provider (2–4), with web search — 250 credits per call.
  • PricingStandard (async) mode — 30% off any of the above tiers (e.g. multi-provider + web search drops from 250 to 212 credits).
  • PricingGET /v1/mentions/search — 35 credits per call.
  • PricingPOST /v1/mentions/crawl — 650 credits flat per crawl.