Reranking

A reranker reads a query and a list of documents and scores how relevant each document is. It is the usual second step after a fast search: retrieve 50–100 candidates with embeddings or keyword search, rerank them, and keep the best few for the model. It noticeably improves answers in RAG pipelines.

POST /v1/rerank takes the familiar rerank request shape. Rerank models include qwen3-reranker-0.6b, qwen3-reranker-4b and qwen3-reranker-8b.

Rerank documents

curl https://api.cloakray.com/v1/rerank \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-reranker-4b",
    "query": "quiet mechanical keyboard",
    "documents": [
      "Linear switches with dampened stabilisers for silent typing",
      "RGB gaming mouse with 12 programmable buttons",
      "Clicky blue switches with a loud tactile bump"
    ],
    "top_n": 2
  }'

{
  "id": "...",
  "results": [
    { "index": 0, "relevance_score": 0.94 },
    { "index": 2, "relevance_score": 0.31 }
  ]
}

Results are sorted by relevance_score, highest first. index points back into your documents array.

Parameters

Parameter	What it does
`model`	Required.
`query`	Required. What you are searching for.
`documents`	Required. The candidates, as strings.
`top_n`	Return only the best N. Defaults to all.
`return_documents`	`true` to include each document's text in the result.

Pricing

Reranking is billed on input tokens — the query plus every document — at the price on the model's page. Keep candidate documents to the passage that matters rather than whole pages.