Skip to main content
POST
Rerank documents by relevance

Authorizations

Authorization
string
header
required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Body

application/json
query
string
required

The search query to rank the documents against.

Maximum string length: 8192
documents
string[]
required

Candidate passages to rerank.

Maximum array length: 200
Maximum string length: 8192
model
string

Reranker model id. Defaults to the gateway's configured completions default. Use "mock" for a deterministic, LLM-free response.

Maximum string length: 256
top_n
integer

Limit the number of returned results. Defaults to all documents; a value of 0 or less is ignored (returns all).

max_tokens_per_doc
integer

Accepted for contract compatibility with native rerankers. Currently advisory (not enforced).

analytics_context
object

Prisme.ai extension. Caller-supplied analytics context.

Response

Successful rerank response (results sorted by relevance_score descending).

id
string
required

Unique identifier for this rerank request.

results
object[]
required

Scored documents, sorted by relevance_score descending.

meta
object