#Rerank

Use reranking to reorder candidate documents by relevance to a query. It is commonly applied after keyword or vector retrieval.

POST https://getrouter.ai/v1/rerank

#Basic request

curl https://getrouter.ai/v1/rerank \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "query": "How do I authenticate API requests?",
    "documents": [
      "Send the API key as a Bearer token in the Authorization header.",
      "Video generation jobs are asynchronous.",
      "Image responses may contain a URL or Base64 data."
    ],
    "top_n": 2,
    "return_documents": true
  }'

The response contains a ranked results array. Each result identifies the source document index and includes a relevance score; the document can also be returned when return_documents is enabled.

#Request fields

#Retrieval workflow

User query
    ↓
Keyword or vector retrieval
    ↓
Candidate documents
    ↓
POST /v1/rerank
    ↓
Top-ranked context
    ↓
Generation model

#Best practices

• Keep the original document index so results can be mapped back safely.
• Retrieve a manageable candidate set before reranking.
• Use top_n to limit the context passed to a generation model.
• Measure retrieval quality with your own data rather than relying on score thresholds copied from another model.
• Do not compare raw scores across different rerank models unless their documentation states that the scales are compatible.

#Next steps

• Embeddings
• Browse rerank models
• Review pricing
• Open the API Reference