Rerank API

By Tokuse
APIRerank
Read in other languages:한국어日本語

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_score before building the final context. Do not assume a fixed score cutoff across queries.
  • top_n limits 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.