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-04-25 — v1.0 Launch

Initial public release. Unified query API across OpenAI, Anthropic, Gemini, and Perplexity, with brand-mention extraction, citation canonicalization, and prepaid credit billing.

Added

  • AddedPOST /v1/ask — primary endpoint. 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 (10¢ flat) — query the crawler-populated brand-mentions database.
  • AddedPOST /v1/mentions/crawl ($2.00 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 2¢; 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

  • PricingCache hit (any tier) — 2¢ per call.
  • PricingSingle provider, no web search — 5¢ per call.
  • PricingSingle provider, with web search — 15¢ per call.
  • PricingMulti-provider (2–4), no web search — 25¢ per call.
  • PricingMulti-provider (2–4), with web search — 75¢ per call.
  • PricingStandard (async) mode — 30% off any of the above tiers (e.g. multi-provider + web search drops from 75¢ to 52¢).
  • PricingGET /v1/mentions/search — 10¢ per call.
  • PricingPOST /v1/mentions/crawl — $2.00 flat per crawl.