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);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 havemodel_type: rerankerinGET /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
{
"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.