Reranking
Score documents against a query and return them in order.
POST /v1/rerank takes a query and a list of documents and returns them scored for relevance, highest first. It is the second pass of a retrieval pipeline: an embedding search is fast and approximate over the whole corpus, and a rerank is slow and accurate over the handful of candidates that search returned.
Where it fits
The usual shape is: embed the query, search a vector store, take the top fifty, rerank them, keep the top five. The first pass optimises for recall over millions of documents; the second optimises for precision over fifty. Doing only the first gives you results that are topically close but often not answers; doing only the second is too slow to run over a corpus.
A request
curl https://api.routehook.ai/v1/rerank \
-H "Authorization: Bearer $ROUTEHOOK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cohere/rerank-v3.5",
"query": "how do credit holds work",
"documents": [
"A hold reserves the ceiling before the call is made.",
"Invoices are issued on the first of the month.",
"The reservation is released when the request fails."
],
"top_n": 2
}'
POST/v1/rerankAvailable
Score a set of documents against a query and return them in relevance order.
What it costs
Billed on the query plus the documents you send. There is no completion, so there is no output axis. Sending fifty candidates costs fifty candidates' worth whether you keep five of them or all of them, so trim the candidate list before the call rather than with top_n after it.