> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From zero to matched news in five minutes, no install, no vectors required.

## 1. Get an API key

Clair is distributed through [RapidAPI](https://rapidapi.com/clairapis-clairapis-default/api/clair-news-api). 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.

<Note>
  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`.
</Note>

## 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.

```sh cURL (text mode) theme={null}
curl -X POST https://clair-news-api.p.rapidapi.com/v1/match \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Artificial Intelligence: foundation models, GPUs, inference, AI labs and chips.",
        "min_score": 0.6,
        "limit": 20
      }'
```

Each result carries the headline, the source link, the **matched snippet**
(`best_chunk`) that explains *why* it matched, and the cosine `score`.

<Note>
  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).
</Note>

## 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.

```sh cURL (vector mode) theme={null}
curl -X POST https://clair-news-api.p.rapidapi.com/v1/match \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{ "model": "bge-m3", "vector": [/* 1024 floats */], "min_score": 0.6 }'
```

## 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`.

```sh cURL (time order) theme={null}
curl -X POST https://clair-news-api.p.rapidapi.com/v1/match \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Artificial Intelligence: foundation models, GPUs, inference, AI labs and chips.",
        "order": "time",
        "since": "2026-07-16T00:00:00Z",
        "min_score": 0.6,
        "limit": 100
      }'
```

<Note>
  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.
</Note>

## 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.

```sh cURL (no query) theme={null}
curl -X POST https://clair-news-api.p.rapidapi.com/v1/match \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{ "since": "2026-07-01T00:00:00Z", "limit": 100 }'
```

`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:

```sh cURL (sources) theme={null}
curl https://clair-news-api.p.rapidapi.com/v1/sources \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com"
```

```json theme={null}
{ "count": 38, "items": ["ABC News", "BBC World News", "Bloomberg - Markets", "..."] }
```

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).

<Card title="Next: how it works" icon="arrow-right" href="/docs/how-it-works">
  Understand the embedding space and the two-stage match so your local scores
  line up with the API's.
</Card>