Rerank

Forward reranking requests through `/v1/rerank` when the selected upstream model supports rerank semantics.

POSThttps://onerouter.com/v1/rerank

Troubleshooting

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

ParameterTypeRequiredDescription
Authorizationstring · requiredrequiredBearer token, formatted as `Bearer YOUR_API_KEY`.
Content-Typestring · requiredrequiredMust be `application/json`.

Request body

ParameterTypeRequiredDescription
modelstringrequiredRerank model ID.
querystringrequiredSearch query or ranking intent.
documentsarrayrequiredDocuments or passages to rank.
top_nintegeroptionalReturn only the top ranked items when supported.
return_documentsbooleanoptionalInclude 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.