Skip to main content
POST
/
v1
/
rerank
curl --request POST \
  --url https://api.mixroute.ai/v1/rerank \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "rerank-v3",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of AI.",
      "Deep learning uses neural networks."
    ],
    "top_n": 3
  }'

{
  "id": "rerank_abc123",
  "model": "rerank-v3",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9856,
      "document": {
        "text": "Machine learning is a subset of artificial intelligence."
      }
    },
    {
      "index": 2,
      "relevance_score": 0.8234,
      "document": {
        "text": "Deep learning uses neural networks with many layers."
      }
    }
  ],
  "usage": {
    "total_tokens": 85
  }
}

​
Document Reranking

The Rerank API reorders documents by relevance to a query, improving retrieval quality in RAG (Retrieval-Augmented Generation) pipelines.

​
Endpoint

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

​
Authentication

Authorization: Bearer sk-xxxxxxxxxx

​
Request Body

ParameterTypeRequiredDescription
modelstringYesReranking model ID
querystringYesSearch query
documentsarrayYesDocuments to rerank
top_nintegerNoNumber of top results to return
return_documentsbooleanNoInclude document text in response

​
Document Format

Documents can be strings or objects: 
// Simple strings
["Document 1 text", "Document 2 text"]

// Objects with metadata
[
  {"text": "Document 1", "id": "doc1"},
  {"text": "Document 2", "id": "doc2"}
]

​
Example Request

curl -X POST https://api.mixroute.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "rerank-v3",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of artificial intelligence.",
      "The weather today is sunny with clear skies.",
      "Deep learning uses neural networks with many layers.",
      "Python is a popular programming language."
    ],
    "top_n": 3,
    "return_documents": true
  }'

​
RAG Pipeline Integration

​
Step 1: Initial Retrieval

# Retrieve candidate documents using embeddings
candidates = vector_store.search(query, top_k=20)

​
Step 2: Rerank

import requests

response = requests.post(
    "https://api.mixroute.ai/v1/rerank",
    headers={"Authorization": "Bearer sk-xxxxxxxxxx"},
    json={
        "model": "rerank-v3",
        "query": query,
        "documents": [doc["text"] for doc in candidates],
        "top_n": 5
    }
)

reranked = response.json()["results"]

​
Step 3: Generate Response

# Use top reranked documents as context
context = "\n".join([r["document"]["text"] for r in reranked])
# Pass to LLM for generation

​
With Document IDs

Track documents through the reranking process: 
curl -X POST https://api.mixroute.ai/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "rerank-v3",
    "query": "climate change effects",
    "documents": [
      {"text": "Rising sea levels threaten coastal cities.", "id": "doc_001"},
      {"text": "Electric vehicles reduce emissions.", "id": "doc_002"},
      {"text": "Global temperatures have increased.", "id": "doc_003"}
    ],
    "top_n": 2
  }'

​
Supported Models

ModelDescription
rerank-v3Latest high-accuracy reranker
rerank-v2Balanced speed and accuracy
rerank-liteFast, cost-effective option

​
Best Practices

  • Over-fetch then rerank: Retrieve more candidates (20-100) then rerank to top 3-10
  • Keep documents concise: Chunk long documents before reranking
  • Combine with embeddings: Use embeddings for initial retrieval, rerank for precision
  • Batch appropriately: Send related documents together for consistent scoring
curl --request POST \
  --url https://api.mixroute.ai/v1/rerank \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "rerank-v3",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of AI.",
      "Deep learning uses neural networks."
    ],
    "top_n": 3
  }'

{
  "id": "rerank_abc123",
  "model": "rerank-v3",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9856,
      "document": {
        "text": "Machine learning is a subset of artificial intelligence."
      }
    },
    {
      "index": 2,
      "relevance_score": 0.8234,
      "document": {
        "text": "Deep learning uses neural networks with many layers."
      }
    }
  ],
  "usage": {
    "total_tokens": 85
  }
}