Rerank

Reranks documents by relevance to a query. Commonly used for the second-stage retrieval in RAG to improve top-K precision.

POST https://wrouter.ai/v1/rerank

Body

Parameter	Type	Required	Notes
model	string	✓	e.g. bge-reranker-v2-m3, jina-reranker-v2, cohere-rerank-3.5
query	string	✓	The query text
documents	array	✓	List of candidate documents (strings)
top_n	integer		Return only the top N most-relevant
return_documents	boolean		Include the original text in the response. Default false

Response

{
  "id": "rerank-xxx",
  "results": [
    {"index": 2, "relevance_score": 0.93, "document": {"text": "..."}},
    {"index": 0, "relevance_score": 0.78}
  ],
  "meta": {
    "api_version": {"version": "1"},
    "billed_units": {"search_units": 1}
  }
}

results[].index refers to the index in the request's documents, sorted by relevance_score desc.

Examples

curl https://wrouter.ai/v1/rerank \
  -H "Authorization: Bearer $WROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is WRouter?",
    "documents": [
      "WRouter is an OpenAI-compatible multi-model gateway.",
      "Today the weather is nice.",
      "Anthropic Claude is one of the models WRouter supports."
    ],
    "top_n": 2,
    "return_documents": true
  }'

import httpx
resp = httpx.post(
    "https://wrouter.ai/v1/rerank",
    headers={"Authorization": "Bearer sk-..."},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "What is WRouter?",
        "documents": [...],
        "top_n": 5,
    },
)
print(resp.json()["results"])

When to use

Typical RAG pipeline:

1. Vector recall (Embeddings) → e.g. top 100 candidates
2. Rerank → narrow to top 5
3. Feed top 5 to Chat Completions

Rerank gives a meaningful precision boost on top-K vs. cosine similarity alone, at the cost of higher latency — that's why it's typically a second stage.