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

# News quickstart

> Search cleaned news, walk the newest articles, filter by source and time, and page safely with an opaque cursor.

## 1. Get an API key

The News API is distributed through
[RapidAPI](https://rapidapi.com/clairapis-clairapis-default/api/clair-news-api).
Subscribe and copy your **`X-RapidAPI-Key`** from the dashboard.

<Note>
  The examples use `clair-news-api.p.rapidapi.com`. Use the exact
  `X-RapidAPI-Host` shown on the listing.
</Note>

## 2. Run a keyword search

Use familiar web-search syntax for phrases, alternatives, and exclusions:

```sh cURL theme={null}
curl -G https://clair-news-api.p.rapidapi.com/v1/news \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  --data-urlencode 'q="central bank" OR inflation -sports' \
  --data-urlencode "from=2026-07-01T00:00:00Z" \
  --data-urlencode "sort_by=published_at" \
  --data-urlencode "limit=25"
```

Clair searches article titles and cleaned content in its own English-language
index. The request does not contact a publisher.

```json theme={null}
{
  "query": "\"central bank\" OR inflation -sports",
  "language": "en",
  "sort_by": "published_at",
  "count": 1,
  "items": [
    {
      "id": "8cbabdf6-31cc-4677-8cf3-a39f8152aa08",
      "title": "Article title",
      "url": "https://publisher.example/article",
      "source": { "name": "Publisher" },
      "description": "Publisher summary or normalized short description",
      "image_url": "https://publisher.example/image.jpg",
      "authors": ["Reporter Name"],
      "language": "en",
      "category": "politics",
      "published_at": "2026-07-29T10:15:30.123456Z",
      "collected_at": "2026-07-29T10:16:04.654321Z",
      "content": "Cleaned article text or feed excerpt",
      "content_available": true,
      "content_truncated": false,
      "is_update": false,
      "relevance_score": 0.42
    }
  ],
  "next_cursor": "OPAQUE_CURSOR"
}
```

The sample values are illustrative. `relevance_score` is local to the current
query, not a probability.

## 3. Choose an ordering

The default `sort_by=published_at` returns matching articles newest first. This
is usually the right choice for monitoring.

Use relevance ordering when you want the strongest text matches first:

```sh cURL theme={null}
curl -G https://clair-news-api.p.rapidapi.com/v1/news \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  --data-urlencode 'q=renewable energy -"sports car"' \
  --data-urlencode "sort_by=relevance"
```

`sort_by=relevance` requires `q`. Both orderings use a stable ID tiebreaker.

## 4. Walk the newest articles

Omit `q` to read the canonical corpus newest first:

```sh cURL theme={null}
curl -G https://clair-news-api.p.rapidapi.com/v1/news \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  --data-urlencode "from=2026-07-29T00:00:00Z" \
  --data-urlencode "limit=100"
```

In this mode, `query` and every `relevance_score` are null. Use it for polling,
incremental ingestion, or a local archive.

## 5. Filter by source

First list the active source names:

```sh cURL 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"
```

Then pass exact names as a comma-separated value:

```sh theme={null}
--data-urlencode "sources=Al Jazeera English,Deutsche Welle (English)"
```

Use `exclude_sources` instead when you want every source except the named
ones. You cannot send both filters in one request. An unknown name returns
`unknown_source`.

## 6. Page with the cursor

When `next_cursor` is not null, repeat the same request and pass it unchanged:

```sh cURL theme={null}
curl -G https://clair-news-api.p.rapidapi.com/v1/news \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: clair-news-api.p.rapidapi.com" \
  --data-urlencode 'q="central bank" OR inflation -sports' \
  --data-urlencode "from=2026-07-01T00:00:00Z" \
  --data-urlencode "sort_by=published_at" \
  --data-urlencode "limit=25" \
  --data-urlencode "cursor=CURSOR_FROM_PREVIOUS_RESPONSE"
```

The cursor is bound to the original query, filters, sort, and
`include_edits` value. Changing them while reusing it returns `bad_cursor`.
Stop when `next_cursor` is null.

## 7. Handle content and revisions

`content_available=false` means Clair has neither a cleaned snippet nor a feed
excerpt for that item. `content_truncated=true` means the response contains the
first 2,000 characters. Clair does not expose a full-article archive.

The default response contains one canonical record per publisher URL. Add:

```sh theme={null}
--data-urlencode "include_edits=true"
```

to include later in-place revisions. Those additional records have
`is_update=true`.

<Card title="Full News API reference" icon="arrow-right" href="/docs/news-api/search">
  Every filter, response field, cursor rule, and error code.
</Card>