# Rerank 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** ```bash 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' ``` **Python** ```python 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)) ``` **TypeScript** ```typescript 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": "", "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](https://docs.privatemind.com/embeddings.html) 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](https://docs.privatemind.com/embeddings.html) for the retrieval half of the pipeline. - [Models](https://docs.privatemind.com/models.html) to identify reranker models in your org's catalog. - [Rate limits](https://docs.privatemind.com/rate-limits.html) for budget and RPM behaviour.