POST /v1/discover

Generate up to 50 query candidates that real users ask about a brand. Each candidate is scored 0–1 and tagged with intent (informational, commercial, comparison, transactional). Use the output to seed /v1/check calls or to schedule a watch.

POST/v1/discover— Discover query candidates for a brand

Pricing — $0.50 / call

Flat per-call price. Cache is 7-day per (brand + industry + language); cache hits still cost $0.50 because the value is the answer, not the upstream call. The result set is an LLM-curated set of candidates derived from a our web search infrastructure /search pass over recent web content + an Anthropic theme-extraction pass.

Quickstart

bash

curl https://api.mentionsapi.com/v1/discover \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "HubSpot",
    "industry": "CRM software",
    "count": 10
  }'

Request body

Field	Type	Description
`brand` required	`string`	Brand name. 1–120 chars. Example: 'HubSpot'.
`industry`optional	`string`	Industry or category hint, used to narrow our web search infrastructure's web search. 1–120 chars. Example: 'CRM software'.
`count`optional	`number`	Number of candidates to return. 1–100. Default 50. Default: `50`
`language`optional	`string`	ISO language code passed to our web search infrastructure `/search`. 2–8 chars. Defaults to 'en'. Default: `en`

Response

json

{
  "request_id": "req_01JBQ2K8H...",
  "brand": "HubSpot",
  "industry": "CRM software",
  "candidates": [
    {
      "query": "best CRM for small business",
      "intent": "comparison",
      "score": 0.92,
      "rationale": "Common comparison query — HubSpot frequently surfaced in answers."
    },
    {
      "query": "HubSpot vs Salesforce",
      "intent": "comparison",
      "score": 0.88,
      "rationale": "Direct competitor query, high commercial intent."
    },
    {
      "query": "HubSpot CRM free tier features",
      "intent": "informational",
      "score": 0.81,
      "rationale": "Brand-specific feature query."
    }
  ],
  "total": 10,
  "cached": false,
  "cost_cents": 50,
  "balance_after_cents": 9950
}

Each candidate carries a rationale field (≤140 chars) so you can audit why it surfaced. The cached flag tells you whether this was a fresh our web search infrastructure pass or an L2 KV hit.

Error codes

Field	Type	Description
`400 invalid_request`optional	`Error`	Schema validation failed.
`402 insufficient_balance`optional	`Error`	Balance below $0.50.
`503 discover_no_context`optional	`Error`	our web search infrastructure returned 0 snippets for this brand+industry. Refunded automatically; try again with a more specific industry hint.

Full error catalog at /docs/errors.