News API

The Clair News API exposes two read-only endpoints over 3 months+ of broad, continuously refreshed editorial coverage:

Endpoint	Purpose
`GET /v1/news`	Search and filter articles or browse the canonical corpus newest first.
`GET /v1/sources`	List exact active publisher names accepted by source filters.
`GET /v1/search?engine=google_news`	Live headlines from news.google.com.
`GET /v1/search?engine=reuters_news`	Search or list Reuters public articles with body.
`GET /v1/search?engine=bloomberg_news`	Live Bloomberg latest listing with article body.
`GET /v1/search?engine=ap_news`	Live AP world-news hub with article body.

Coverage and suitable uses

Clair includes editorial reporting from validated publishers across world affairs, politics, business, technology, science, health, sports, entertainment, and the environment. Results retain publisher attribution, original URLs, timestamps, category, bylines, images, descriptions, and a bounded cleaned snippet where available. The index excludes non-article and utility formats such as weather pages, recipes, audio, video, podcasts, and galleries. Duplicate coverage and superseded edits are collapsed by default. Clair is not a full-article archive. Live publisher scrapes — Google News, Reuters, Bloomberg, and Associated Press — fetch public pages at request time on GET /v1/search. Use the index when you want a corpus; use a live SKU when you want one publisher’s current listing with (for Reuters/Bloomberg/AP) article body. Use the API for monitoring, alerts, research, trend analysis, media intelligence, searchable feeds, incremental ingestion, and as an acquisition layer for customer-owned semantic search or RAG systems. See the product overview and dataset coverage before you integrate.

How requests are served

Indexed GET /v1/news reads a prebuilt corpus. Background workers discover, fetch, clean, and index publisher material. Those public requests never crawl a URL supplied by a caller, contact a publisher during the request, or invoke an embedding model. Live SKUs on GET /v1/search fetch the public listing at request time. See each publisher page for page size and hydration rules.

Base URL and authentication

Call https://api.clair.im with a Clair dashboard key:

Authorization: Bearer YOUR_KEY

Create keys under API keys. One key and wallet cover News, Jobs, and the rest of the catalog. See Authentication.

The News API is also listed on RapidAPI for marketplace subscribers. First-party examples in these docs use api.clair.im.

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.

language defaults to en. Pass uk, ko, fr, and other ISO 639-1 codes for that slice, or all for every detected language. Keyword search still uses the English analyzer; chronological walks are language-accurate. 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`.
`language`	`en`	ISO 639-1 code (`uk`, `ko`, `fr`, …) or `all`.
`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://api.clair.im/v1/news \
  -H "Authorization: Bearer YOUR_KEY" \
  --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 a valid Bearer key.
`429`	`quota_exceeded`	The wallet is empty or the account 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.

Indexed news

Live publishers

Coverage and suitable uses

How requests are served

Base URL and authentication

Search or walk the corpus

Query parameters

Response

Content and revision semantics

Sources

Errors

​Coverage and suitable uses

​How requests are served

​Base URL and authentication

​Search or walk the corpus

​Query parameters

​Response

​Content and revision semantics

​Cursor pagination

​Sources

​Errors

Coverage and suitable uses

How requests are served

Base URL and authentication

Search or walk the corpus

Query parameters

Response

Content and revision semantics

Cursor pagination

Sources

Errors