Rerank API
POST https://tokuse.com/v1/rerank scores candidate passages against a query. Run it after an initial keyword or vector search to move the best passages to the top before sending them to a chat model.
| Item | Value |
|---|---|
| Method and path | POST /v1/rerank |
| Authentication | Authorization: Bearer $TOKUSE_API_KEY |
| Models | A rerank model enabled on the upstream account |
| Pricing | Tokuse pricing and the upstream provider console |
Endpoint and authentication
Use a Bearer token on https://tokuse.com/v1/rerank. The request carries a query, a documents array, and an optional top_n. Documents can be plain strings; a common flow sends the titles and chunks returned by a vector search.
Models and prerequisites
Reranking needs its own model. A chat model alias will not work here. The upstream account must have a rerank model enabled, and the model ID should come from the current catalog.
Request
curl https://tokuse.com/v1/rerank \
-H "Authorization: Bearer $TOKUSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "your-rerank-model",
"query": "How should I rotate an API key?",
"documents": [
"Create a new key, update every client, then revoke the old key.",
"The pricing page lists input and output token rates.",
"Deployments run through the staging gateway first."
],
"top_n": 2
}'
Response
{
"results": [
{
"index": 0,
"relevance_score": 0.94
},
{
"index": 2,
"relevance_score": 0.21
}
],
"usage": {
"total_tokens": 41
}
}
Each result points back to the input position through index. Keep the original document list so you can map scores to text.
Notes and limits
- Enable a rerank model on the upstream account before calling the endpoint. Without it, the gateway has no model to route to.
- Sort results by
relevance_scorebefore building the final context. Do not assume a fixed score cutoff across queries. top_nlimits how many scored documents come back. Send only the candidate set you actually need to rerank; long lists cost more and add latency.
Billing
This reference does not include prices. Rerank is billed per request or per input token depending on the upstream model. Confirm the rate on the Tokuse pricing page and in the upstream provider console; gateway pricing is at /pricing.