Skip to main content
POST

Authorizations

​
X-RapidAPI-Key
string
header
required

Your RapidAPI key. Also send X-RapidAPI-Host with the value shown on the Clair RapidAPI page.

Body

application/json

Send at most one of vector or text. Sending neither is valid and means "no query": the corpus, newest-first.

​
model
string
default:bge-m3

Embedding-space id for vector mode. Only "bge-m3" at launch. Ignored for text mode (we always embed into bge-m3).

​
vector
number[]

The entity's 1024-dim, L2-normalized bge-m3 vector. Omit when using text or when you want no query.

Required array length: 1024 elements
​
text
string

A plain-language entity/query (e.g. a name plus a sentence). We embed it with bge-m3 server-side, so no local model is needed. Omit when using vector or when you want no query.

Required string length: 1 - 4000
​
order
enum<string>
default:time

Newest-first (time, default) or best-first (relevance). relevance needs a query and has no cursor.

Available options:
relevance,
time
​
min_score
number
default:0.5

Cosine floor; articles below this are dropped. Ignored when there is no query.

Required range: -1 <= x <= 1
​
since
string<date-time>

Inclusive ISO-8601 lower bound on event_time.

​
until
string<date-time>

Inclusive ISO-8601 upper bound on event_time.

​
limit
integer
default:50

Page size. The same cap applies to every mode, so an article costs the same however you asked for it.

Required range: 1 <= x <= 100
​
cursor
string

Opaque keyset cursor from a previous page's next_cursor. Only valid with order=time.

​
include_edits
boolean
default:false

Publishers edit articles in place (same URL, new headline/body). Every revision is stored, but by default a result is one row per article: the FIRST-published version, with its original timestamp. Set true to return the full edit history (e.g. to study how coverage of an event evolved). Default false, so results are deduplicated.

​
sources
string[]

Restrict results to these sources, given by the exact name strings GET /v1/sources returns. Mutually exclusive with exclude_sources. An unknown name is rejected with invalid_request (never a silent empty page). Note: a very selective include over a broad query can under-fill a page (matches become sparse in relevance order), so widen the source set or the query if so.

Required array length: 1 - 50 elements
​
exclude_sources
string[]

Drop these sources from results, given by the exact name strings GET /v1/sources returns. Mutually exclusive with sources. An unknown name is rejected with invalid_request.

Required array length: 1 - 50 elements

Response

A page of articles.

​
model
string
Example:

"bge-m3"

​
order
string
Example:

"relevance"

​
count
integer
Example:

20

​
items
object[]
​
next_cursor
string | null

Present only with order=time; null when there are no more pages.