Rerank
Forward reranking requests through `/v1/rerank` when the selected upstream model supports rerank semantics.
https://onerouter.com/v1/rerankTroubleshooting
Errors carry an HTTP status and a JSON error body. See Errors & Retries for the full list.
Model availability
Rerank works only with an upstream model that exposes rerank semantics. Pass that model's ID in model (shown as <rerank-model-id> in the example below). Rerank models are not listed on the website catalog — confirm the exact ID with your provider.
Overview
Rerank scores a set of documents against a query and returns them ordered by relevance. It is most useful as a second stage in retrieval: first fetch candidate documents with embeddings or keyword search, then rerank the top candidates to put the best matches first before sending them to a model. Pass the query and a documents array; the response lists each document's index and relevance_score.
Request headers
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string · required | required | Bearer token, formatted as `Bearer YOUR_API_KEY`. |
| Content-Type | string · required | required | Must be `application/json`. |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | required | Rerank model ID. |
| query | string | required | Search query or ranking intent. |
| documents | array | required | Documents or passages to rank. |
| top_n | integer | optional | Return only the top ranked items when supported. |
| return_documents | boolean | optional | Include the original document text in each result. |
The response
Returns results sorted by descending relevance_score (see the panel on the right). Each item references the input by index; if return_documents is set, the document text is included too.
Model-dependent features
OneRouter keeps protocol compatibility and forwards model-specific parameters where supported. Features such as tool calling, structured output, reasoning, prompt caching, web search, image input, audio input, video generation, and provider-specific options depend on the selected model and upstream provider. Check the model detail page before relying on a feature in production.