Skip to main content

​
1. Get an API key

Create a Clair account and a key under API keys. Send it as Authorization: Bearer YOUR_KEY. See Authentication. Use familiar web-search syntax for phrases, alternatives, and exclusions:
cURL
Clair searches article titles and cleaned content. Omit language for the English slice; pass language=ko (or uk, fr, all, …) for other languages. The request does not contact a publisher.
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:
cURL
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:
cURL
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:
cURL
Then pass exact names as a comma-separated value:
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:
cURL
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:
to include later in-place revisions. Those additional records have is_update=true.

Full News API reference

Every filter, response field, cursor rule, and error code.