Authentication, credits, and errors

Every Clair API shares one origin, one key, and one credit wallet.


Origin	`https://api.clair.im`
Header	`Authorization: Bearer YOUR_KEY`
Keys	Dashboard → API keys

curl -G https://api.clair.im/v1/news \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "q=inflation" \
  --data-urlencode "limit=5"

New accounts receive 250 free credits and a 10 requests/minute cap. Create a key once and copy it; Clair cannot show the secret again.

Indexed News and Jobs remain available on RapidAPI listings. First-party docs, the playground, and live scrapes (Google Search, publisher pages, Glassdoor, Trustpilot, Product Hunt, website contacts) use api.clair.im and a Clair Bearer key.

Credits

Requests debit the wallet before the handler runs. An empty wallet returns 429 with quota_exceeded. Subscription credits spend first; purchased credits do not expire with the plan.

Family	Credits	Examples
Indexed	1	`GET /v1/news`, `GET /v1/jobs`, taxonomies, market intelligence
Live search	5	`engine=google_search`, `engine=google_news`
Live listing / article	8	Reuters, Bloomberg, AP, Glassdoor, Trustpilot, Product Hunt
Website contacts	10	`GET /v1/contacts`

Each page on a live scraper is a new billed request. Indexed News and Jobs paginate with limit and cursor inside one credit per call.

Errors

Mounted endpoints return a stable error code and human detail. Branch on the code; do not parse detail.

{ "error": "bad_request", "detail": "q is required" }

Status	`error`	Meaning
`400`	`bad_request`	A parameter failed validation.
`400`	`bad_cursor`	The cursor is malformed, bound to different inputs, or this engine does not paginate.
`400`	`locked_parameter`	A pin-locked filter was sent (for example `limit` on a live scrape, or `sources` on a publisher engine).
`400`	`empty_query`	News keyword search normalized to nothing searchable.
`400`	`unknown_source`	A News source name is not in `GET /v1/sources`.
`400`	`unknown_skill`	A Jobs skill is outside the reviewed vocabulary.
`401`	`unauthorized`	Missing or invalid Bearer key.
`403`	`forbidden`	This listing cannot query that engine.
`404`	`not_found`	No Trustpilot profile, Product Hunt product, or canonical resource.
`429`	`quota_exceeded`	Wallet is empty or the plan rate cap was hit.
`500`	`internal`	Unexpected origin error.
`502`	`scrape_failed`	The live page could not be fetched or parsed. Indexed APIs never return this.
`503`	`product_unavailable`	The product is not ready, or credits could not be reached.
`503`	`overloaded`	This endpoint hit its per-machine concurrency limit.
`504`	`timeout`	The live scrape exceeded its deadline.

Origin responses include X-Request-ID. Include it when reporting a problem. Honor Retry-After on 503.

Pagination

Indexed News and Jobs use limit (default 25, max 100) and an opaque cursor. Pass next_cursor unchanged. Changing filters while reusing a cursor returns bad_cursor. Live scrapes use 1-based page. They return next_cursor: null. Do not send limit or cursor. Google Search pages are 10 organic hits (page max 10). Reuters pages are 20 articles. Google News, Bloomberg, AP, and Product Hunt listings are a single page (page must be 1). Trustpilot and Glassdoor forward page to the public listing.

​Credits

​Errors

​Pagination

Credits

Errors

Pagination