Quickstart

Make your first call in 60 seconds. You'll get back structured brand mentions across whichever providers you list.

1. Get an API key

Sign up (no credit card required), open the dashboard, and click Create new key. Save the key in a password manager — we only display it once.

Get my key

2. Make a call

Pick your favorite tab below. The body shape is identical across languages.

POST /v1/ask
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer $MENTIONSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "quick",
    "query": "best CRM for small business",
    "brand": "HubSpot"
  }'

3. Read the response

The response has a top-level providers array (one entry per provider you asked for, in the order you listed). Each entry is either a successful ProviderResult or a per-provider ProviderError. Brand mentions and citations roll up at the top level so you don't have to aggregate.

json
{
  "request_id": "2e6b…",
  "id": "2e6b…",
  "cached": false,
  "cache_tier": "miss",
  "providers": [
    {
      "provider": "openai",
      "model": "gpt-4o-2024-11-20",
      "content": "Qdrant and Weaviate are the most-recommended…",
      "citations": [
        { "url": "https://qdrant.tech", "title": "Qdrant — Vector DB" }
      ],
      "tokens": { "input": 64, "output": 312 },
      "latency_ms": 1240
    }
  ],
  "brand_mentions": [
    { "brand": "Qdrant",   "provider": "openai", "rank": 1, "sentiment": "positive", "context": "Qdrant and Weaviate are…" },
    { "brand": "Weaviate", "provider": "openai", "rank": 2, "sentiment": "positive", "context": "Qdrant and Weaviate are…" }
  ],
  "citations": [
    {
      "canonical_url": "https://qdrant.tech",
      "domains": ["qdrant.tech"],
      "providers_cited": ["openai"],
      "title": "Qdrant — Vector DB"
    }
  ],
  "usage": {
    "billable_units": 2,
    "latency_ms": 1420,
    "cost_cents": 25,
    "cost_breakdown": {
      "our_price_cents": 25,
      "upstream_cost_cents_estimate": 4,
      "margin_cents": 21,
      "by_provider": [ /* per-provider token + upstream estimate */ ]
    }
  }
}

On a partial failure (one provider 5xxs, others succeed), the HTTP status stays 200 and the failing provider shows up as { provider, error: { code, message } } inside the same providers array. You are not charged for failed providers.

Next steps