Skip to main content

​
1. Get an API key

Clair is distributed through RapidAPI. Subscribe to the Clair API and copy your X-RapidAPI-Key from the dashboard. RapidAPI handles your plan, quota, and billing; every request you make carries that key.
The examples below use the RapidAPI host clair-news-api.p.rapidapi.com. Use the exact host shown on the Clair API’s RapidAPI page; it appears as X-RapidAPI-Host.

​
2. Match your first entity

The fastest path needs no install and no vectors: describe the entity in plain text and Clair embeds it for you, then returns the news it links to, ranked, with the matched snippet that explains each hit.
cURL (text mode)
Each result carries the headline, the source link, the matched snippet (best_chunk) that explains why it matched, and the cosine score.
Send at most one of text or vector; both together is a 422. Sending neither is valid and means “no query”: you get the corpus, newest-first (see step 5). If text mode is briefly unavailable you’ll get a 503; retry, or send a precomputed vector (below).

​
3. Advanced: send your own vector

If you already embed with bge-m3 (1024-dim, L2-normalized), skip our embedding and send the vector directly: the fully reproducible, no-server-model path.
cURL (vector mode)

​
4. Monitor: everything matching, since your last check

"order": "time" returns every article at or above your score floor in the window, newest first, not a top-N sample. That’s the polling loop: keep the event_time of the newest article you saw, pass it as since next time, and page with the cursor from the previous response until next_cursor is null.
cURL (time order)
Timestamps are full ISO-8601: 2026-07-16T00:00:00Z, not 2026-07-16. The event_time we return is the same format, so you can pass one straight back as since without reformatting it.order=time is the default, so you can omit it. Returning everything above min_score means collecting the whole match set, so a query that matches too much returns 422 too_many_matches; raise min_score, or narrow since. You’ll never get a silently shortened page.

​
5. Pull the corpus itself

Omit the query entirely and /v1/match becomes a chronological walk of the whole corpus: no score, no cap at all, keyset-paginated to the end. This is the bulk read; there’s no separate endpoint for it.
cURL (no query)
score and best_chunk come back null; you didn’t ask anything, so nothing was scored.

​
6. See the sources

GET /v1/sources lists the outlets we actively serve, by name:
cURL (sources)
Those names are the picker for source filtering: pass any of them to /v1/match as sources (keep only these) or exclude_sources (drop these).

Next: how it works

Understand the embedding space and the two-stage match so your local scores line up with the API’s.