Get API key

Rerank

View as Markdown

Re-rank documents by relevance to a query with a cross-encoder.

POST /v1/rerank scores how well each document answers a query and returns the documents ordered by relevance. It uses a cross-encoder, a model that reads the query and each document together, so it is more precise than comparing embedding vectors. The response follows Cohere's rerank API.

curl -s "https://api.privatemind.com/v1/rerank" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-reranker-4b",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "London is the capital of England.",
      "Berlin is the capital of Germany."
    ],
    "top_n": 3
  }' | jq '.results'
import requests

resp = requests.post(
    "https://api.privatemind.com/v1/rerank",
    headers={"Authorization": f"Bearer {PMIND_KEY}"},
    json={
        "model": "qwen3-reranker-4b",
        "query": "What is the capital of France?",
        "documents": [
            "Paris is the capital of France.",
            "London is the capital of England.",
            "Berlin is the capital of Germany.",
        ],
        "top_n": 3,
    },
)
for r in resp.json()["results"]:
    print(r["index"], round(r["relevance_score"], 3))
const resp = await fetch('https://api.privatemind.com/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PMIND_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'qwen3-reranker-4b',
    query: 'What is the capital of France?',
    documents: [
      'Paris is the capital of France.',
      'London is the capital of England.',
      'Berlin is the capital of Germany.',
    ],
    top_n: 3,
  }),
});
const { results } = await resp.json();
console.log(results);
Note

The OpenAI SDK has no rerank method, so call this endpoint over plain HTTP. Keys, model ids and rate limits work as on the other endpoints.

Parameters

  • model (required): the id of a reranker model. Reranker models have model_type: reranker in GET /v1/models.
  • query (required): the search query to score documents against.
  • documents (required): an array of strings to rank.
  • top_n (default: all): return only the N highest-scoring documents.

Response

JSON
{
  "id": "score-...",
  "model": "<reranker-model-id>",
  "results": [
    { "index": 0, "relevance_score": 0.997, "document": { "text": "Paris is the capital of France." } },
    { "index": 1, "relevance_score": 0.694, "document": { "text": "London is the capital of England." } },
    { "index": 2, "relevance_score": 0.472, "document": { "text": "Berlin is the capital of Germany." } }
  ],
  "usage": { "prompt_tokens": 42, "total_tokens": 42 }
}

results is sorted by relevance_score (0 to 1), highest first. Each index is the document's position in your documents array, so you can match scores to your own records. You're billed for input tokens only.

Two-stage retrieval

Use rerank with Embeddings for retrieval-augmented generation (RAG): finding the documents relevant to a question and passing them to a model with it. Embeddings pull a broad set of candidates cheaply, then rerank re-orders them and you keep the top few. The cross-encoder is too costly to run over a whole corpus, so embeddings narrow the field first. Fewer, better-matched documents lower cost and latency and improve the model's answers.

Where next

  • Embeddings for the retrieval half of the pipeline.
  • Models to identify reranker models in your org's catalog.
  • Rate limits for budget and RPM behaviour.