Skip to main content
POST
Python

Authorizations

Authorization
string
header
required

An account API key. Send it as Authorization: Bearer <key>.

Body

application/json

The request body of POST /v1/rerank.

model
string
required

The rerank model, named by its id or alias.

query
string
required

The search query the documents are ranked against.

documents
(string | Document object · object)[]
required

The documents to rank, from 1 to 1000: strings, or objects with text.

Required array length: 1 - 1000 elements

One document to rank: plain text, or an object carrying it.

models
string[] | null

Fallback models, tried in order when model cannot answer: none of its providers served it. At most 3, and only the model that answered is billed. A NagaAI extension in OpenRouter's shape.

Maximum array length: 3
routing
object | null

How NagaAI picks the providers for this request: max_price removes the ones above it and can fail the request. A NagaAI extension.

top_n
integer<int64> | null

How many of the most relevant documents to return. All of them when absent.

Required range: x >= 1
return_documents
boolean
default:true

Whether each result carries its document's text. true when absent.

Response

The ranking. results carries the documents most relevant first, each with its index in the request and its score; usage carries the token count behind the charge.

The body of a successful POST /v1/rerank.

id
string
required

The identifier of this rerank, minted by the gateway.

model
string
required

The model that ranked, as the catalog id the request resolved to.

results
object[]
required

The documents, most relevant first, cut to top_n.

usage
object
required

What the request was billed on.