Rerank

Re-rank a list of documents against a query using Cohere, Voyage, Jina, or Mixedbread reranker models.

Overview

The Rerank API takes a query and a list of candidate documents and returns the documents re-sorted by relevance. Reranking is the standard second stage of a retrieval pipeline: a vector index returns 50-100 candidates by embedding similarity, then a reranker uses a cross-encoder to score each (query, document) pair and surface the top K.

AllRoutes supports the major commercial rerankers behind a single endpoint, normalizing Cohere's, Voyage's, Jina's, and Mixedbread's wire formats so you can swap providers by changing one model identifier.

Endpoint

POST https://api.allroutes.ai/v1/rerank

Request Body

Field	Type	Required	Description
`model`	string	Yes	Reranker model identifier (e.g., `rerank-english-v3.0`, `voyage-rerank-2`)
`query`	string	Yes	The query to rank documents against
`documents`	array	Yes	Array of strings or `{text: string}` objects
`top_n`	integer	No	Return only the top N results (default: all)
`return_documents`	boolean	No	Include document text in the response (default: `true`)
`max_chunks_per_doc`	integer	No	Cohere/Jina chunking limit

Example Request

curl https://api.allroutes.ai/v1/rerank \
  -H "Authorization: Bearer allroutes_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital and most populous city of France.",
      "Berlin is the capital of Germany.",
      "The Eiffel Tower is in Paris.",
      "France has a population of about 67 million.",
      "Madrid is the capital of Spain."
    ],
    "top_n": 3
  }'

Response Format

{
  "id": "rerank-abc123",
  "model": "rerank-english-v3.0",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.987,
      "document": {"text": "Paris is the capital and most populous city of France."}
    },
    {
      "index": 2,
      "relevance_score": 0.612,
      "document": {"text": "The Eiffel Tower is in Paris."}
    },
    {
      "index": 3,
      "relevance_score": 0.481,
      "document": {"text": "France has a population of about 67 million."}
    }
  ],
  "usage": {
    "search_units": 5,
    "billed_units": {"search_units": 5}
  }
}

Field	Description
`results[].index`	Position of the document in the original `documents` array
`results[].relevance_score`	Score 0.0-1.0; higher is more relevant
`results[].document.text`	Original text (omitted when `return_documents: false`)
`usage.search_units`	Billing unit (one per query-document pair)

Results are always sorted by relevance_score descending.

Supported Models

Model	Provider	Languages	Max Doc Tokens
`rerank-english-v3.0`	Cohere	English	4096
`rerank-multilingual-v3.0`	Cohere	100+ languages	4096
`voyage-rerank-2`	Voyage AI	English	16000
`voyage-rerank-2-lite`	Voyage AI	English	8000
`jina-reranker-v2-base-multilingual`	Jina	100+ languages	8192
`mxbai-rerank-large-v1`	Mixedbread	English	512
`mxbai-rerank-base-v1`	Mixedbread	English	512

SDK Examples

Python

import os
from allroutes import AllRoutesClient

client = AllRoutesClient(api_key=os.environ["ALLROUTES_API_KEY"])

results = client.rerank(
    model="rerank-english-v3.0",
    query="What is the capital of France?",
    documents=[
        "Paris is the capital and most populous city of France.",
        "Berlin is the capital of Germany.",
        "The Eiffel Tower is in Paris.",
    ],
    top_n=2,
)

for r in results["results"]:
    print(f"#{r['index']} score={r['relevance_score']:.3f}: {r['document']['text']}")

Node.js

const results = await client.rerank.create({
  model: "rerank-english-v3.0",
  query: "What is the capital of France?",
  documents: [
    "Paris is the capital and most populous city of France.",
    "Berlin is the capital of Germany.",
    "The Eiffel Tower is in Paris.",
  ],
  top_n: 2,
});

for (const r of results.results) {
  console.log(`#${r.index} score=${r.relevance_score.toFixed(3)}: ${r.document.text}`);
}

Two-Stage Retrieval Pattern

The canonical RAG flow combines Embeddings (recall) with reranking (precision):

# Stage 1: vector search returns 50 candidates
candidates = vector_store.search(query, k=50)

# Stage 2: rerank to top 5
reranked = client.rerank(
    model="rerank-english-v3.0",
    query=query,
    documents=[c.text for c in candidates],
    top_n=5,
)

top_docs = [candidates[r["index"]] for r in reranked["results"]]

A reranker typically lifts top-5 precision by 15-30 points over pure embedding similarity, especially for queries that share keywords with non-relevant documents.

Pricing

Rerankers bill in search units, not tokens. One search unit equals one (query, document) pair. Costs vary by provider:

Model	Cost per 1K search units
Cohere v3	$2.00
Voyage Rerank 2	$0.05
Jina v2	$0.02
Mixedbread large	$0.10

Use BYOK for 0% commission on top of these provider rates.

Error Codes

Status	Description
`400`	Empty documents array, query too long, or invalid model
`401`	Missing or invalid API key
`402`	Insufficient credits
`413`	Document exceeds the model's token limit
`429`	Rate limit exceeded

Troubleshooting

All scores are low (< 0.1) -- the query and documents are likely in different languages. Switch to a multilingual model.
Top result looks wrong -- check that you didn't truncate documents below their semantic core. Try voyage-rerank-2 for longer contexts.
Slow responses -- Cohere multilingual is the slowest; Mixedbread is fastest. Cache aggressively when query patterns repeat.