Introduction

The Clair News API exposes two read-only endpoints over a continuously maintained news index:

Method	Path	Purpose
`GET`	`/v1/news`	Search cleaned English-language articles or walk the corpus newest first.
`GET`	`/v1/sources`	List the exact active source names accepted by News filters.

Clair collects and cleans publisher material in the background. Public requests query the prebuilt index only. They never crawl a URL supplied by a caller, contact a publisher during the request, or invoke an embedding model.

Base URL and authentication

The News API is distributed through RapidAPI. Send your key and the News API host on every request:

X-RapidAPI-Key: YOUR_RAPIDAPI_KEY
X-RapidAPI-Host: clair-news-api.p.rapidapi.com

RapidAPI owns key issuance, plan quotas, rate limiting, and billing. There is no separate Clair account.

Use the exact host shown on the RapidAPI listing. The Jobs API is a separate listing with a separate host, even when you use the same RapidAPI key.

Search or walk the corpus

q is optional:

With q, Clair runs English full-text search across title and cleaned content. Title matches receive more weight.
Without q, Clair returns the canonical corpus newest first. This is the simplest path for polling or maintaining a local mirror.

The query syntax supports quoted phrases, uppercase OR, and minus-prefixed exclusions:

"central bank" OR inflation -sports

A query that contains only English stop words returns empty_query instead of quietly returning no results.

Query parameters

Parameter	Default	Contract
`q`	none	Search expression, 1–300 characters. Supports quoted phrases, uppercase `OR`, and `-excluded` terms.
`sources`	all	Comma-separated exact names from `GET /v1/sources`, at most 50.
`exclude_sources`	none	Comma-separated exact names, at most 50. Mutually exclusive with `sources`.
`from`	none	Inclusive RFC 3339 publication timestamp.
`to`	none	Inclusive RFC 3339 publication timestamp. Must not precede `from`.
`sort_by`	`published_at`	`published_at` or `relevance`. Relevance sorting requires `q`.
`category`	all	`general`, `world`, `politics`, `business`, `technology`, `science`, `health`, `sports`, `entertainment`, or `environment`.
`include_edits`	`false`	Include later revisions that share the same publisher URL.
`limit`	`25`	Page size from 1 to 100.
`cursor`	none	Opaque continuation token returned by the preceding page.

See Search news for the generated request playground and complete schema.

Response

{
  "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.

Content and revision semantics

content is a bounded cleaned snippet when extraction succeeded, a feed excerpt when one was available, or null when neither was available. Clair does not expose a full-article archive.

content_available tells you whether content is present.
content_truncated is true when Clair capped the returned snippet at 2,000 characters.
description is publisher-provided summary metadata when available.
image_url and authors are nullable/empty when the publisher did not provide reliable values.
category is a deterministic source/section category. Cross-cutting events such as elections, crimes, conflicts, and disasters remain keyword queries.
is_update marks a later in-place revision of the same publisher URL.
relevance_score is a query-local value from 0 to 1. It is not a probability and is null when q is absent.

By default, Clair returns only the canonical version of each publisher URL. Set include_edits=true when a revision history matters to your application. published_at is the publisher time. collected_at is when Clair ingested that record. Both preserve microseconds in the response and cursor.

Cursor pagination

When next_cursor is not null, repeat the exact search and pass the cursor unchanged:

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 "sort_by=published_at" \
  --data-urlencode "cursor=CURSOR_FROM_PREVIOUS_RESPONSE"

The cursor is bound to the query, filters, sort, and revision mode that created it. Changing any of them while reusing the cursor returns bad_cursor. Stop when next_cursor is null. Exact totals are intentionally absent from the request path. Walk next_cursor for a stable result stream rather than depending on a broad archive count.

Sources

GET /v1/sources returns active names alphabetically:

{
  "count": 2,
  "items": [
    "Al Jazeera English",
    "Deutsche Welle (English)"
  ]
}

Pass those strings exactly to sources or exclude_sources. An unknown name returns unknown_source rather than silently producing an empty page.

Errors

Product-handler failures use { "error": "...", "detail": "..." }. Authorization and gateway failures may contain only error. Branch on the stable code; detail is human-readable and may change. Validation failures return an array of details, while typed failures return a string.

Status	`error`	Meaning
`400`	`bad_request`	One or more parameters failed validation.
`400`	`bad_cursor`	The cursor is malformed or belongs to different inputs.
`400`	`empty_query`	English normalization left no searchable terms.
`400`	`unknown_source`	A source name is not in `GET /v1/sources`.
`401`	`unauthorized`	The request is missing valid RapidAPI authorization.
`429`	Gateway-managed	The RapidAPI plan rate limit was exceeded.
`500`	`internal`	An unexpected internal error occurred.
`503`	`dependency_unavailable`	The shared API platform is not ready.
`503`	`product_unavailable`	The News product failed its readiness check.
`503`	`overloaded`	This endpoint reached its per-machine concurrency limit.
`504`	`timeout`	Search exceeded its processing deadline.

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

Get started

Endpoints

Introduction

Base URL and authentication

Search or walk the corpus

Query parameters

Response

Content and revision semantics

Sources

Errors

​Base URL and authentication

​Search or walk the corpus

​Query parameters

​Response

​Content and revision semantics

​Cursor pagination

​Sources

​Errors

Base URL and authentication

Search or walk the corpus

Query parameters

Response

Content and revision semantics

Cursor pagination

Sources

Errors