Rerank
Score and reorder a list of candidate documents for a query using a cross-encoder reranker. A common pattern: do a fast vector search with embeddings, then rerank the top results with a more accurate cross-encoder.
POST
/v1/rerankRequest
📋Request
1{
2 "model": "your-reranker-model",
3 "query": "What is photosynthesis?",
4 "documents": [
5 "Photosynthesis is the process by which plants make food from sunlight.",
6 "The Eiffel Tower is in Paris.",
7 "Chlorophyll is the green pigment in plant cells."
8 ],
9 "top_n": 2
10}Parameters
modelstringrequired
Reranker model id (type: reranker).
querystringrequired
The search query.
documentsstring[]required
Candidate documents to score against the query.
top_ninteger
Return only the top-N most relevant documents.
return_documentsboolean
If true, include each document text in the response.
Response
📋200 OK
1{
2 "object": "list",
3 "model": "your-reranker-model",
4 "results": [
5 { "index": 0, "relevance_score": 0.984 },
6 { "index": 2, "relevance_score": 0.612 }
7 ],
8 "usage": { "total_tokens": 64 }
9}ℹ
Score range
Models with the
scoreNormalized capability return scores in [0, 1]; others may return raw cross-encoder logits. Always sort by descending score.