Rerank

POST /v1/rerank scores how well each document answers a query and returns them ordered by relevance. It uses a cross-encoder, which reads the query and each document together, so it is more precise than comparing embedding vectors. The response shape matches 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);

Parameters

• model (required): id of a reranker model. In GET /v1/models, reranker models report an empty supported_parameters array; identify them by id or model_type.
• query (required): the search query to score documents against.
• documents (required): an array of strings to rank. Each is read together with the query.
• top_n (default: all): return only the N highest-scoring documents.

Response

{
  "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 descending. Each index maps back to the document's position in the request documents array, so you can apply the scores to your own records. Scores range from 0 to 1. Billing is on input tokens only.

Two-stage retrieval

Rerank pairs with Embeddings for retrieval-augmented generation. Use embeddings to pull a broad candidate set cheaply by vector similarity, then rerank to re-order those candidates by true relevance and keep the top few. The cross-encoder is more accurate than vector similarity but too expensive to run over a whole corpus, so the embedding stage narrows the field first. Feeding fewer, better-matched documents to the model lowers cost and latency and improves answers.

Where next

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