Skip to main content
POST
/
rerank
Submit a rerank request
curl --request POST \
  --url https://openrouter.ai/api/v1/rerank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    "Paris is the capital of France.",
    "Berlin is the capital of Germany."
  ],
  "model": "cohere/rerank-v3.5",
  "query": "What is the capital of France?",
  "top_n": 3
}
'
{
  "id": "gen-rerank-1234567890-abc",
  "model": "cohere/rerank-v3.5",
  "results": [
    {
      "document": {
        "text": "Paris is the capital of France."
      },
      "index": 0,
      "relevance_score": 0.98
    }
  ],
  "usage": {
    "search_units": 1,
    "total_tokens": 150
  }
}

Authorizations

​
Authorization
string
header
required

API key as bearer token in Authorization header

Body

application/json

Rerank request input

​
documents
(string | object)[]
required

The list of documents to rerank. Documents may be plain strings, or structured objects with text and/or image for multimodal models.

Minimum array length: 1

A document to rerank. Either a plain string, or a structured object with optional text and/or image.

Example:
[
  "Paris is the capital of France.",
  "Berlin is the capital of Germany."
]
​
model
string
required

The rerank model to use

Example:

"cohere/rerank-v3.5"

​
query
string
required

The search query to rerank documents against

Example:

"What is the capital of France?"

​
provider
object | null

Provider routing preferences for the request.

Example:
{ "allow_fallbacks": true }
​
top_n
integer

Number of most relevant documents to return

Required range: x >= 1
Example:

3

Response

Rerank response

Rerank response containing ranked results

​
model
string
required

The model used for reranking

Example:

"cohere/rerank-v3.5"

​
results
object[]
required

List of rerank results sorted by relevance

Example:
[
  {
    "document": { "text": "Paris is the capital of France." },
    "index": 0,
    "relevance_score": 0.98
  }
]
​
id
string

Unique identifier for the rerank response (ORID format)

Example:

"gen-rerank-1234567890-abc"

​
provider
string

The provider that served the rerank request

Example:

"Cohere"

​
usage
object

Usage statistics

Example:
{ "search_units": 1, "total_tokens": 150 }