Rerank API

The Rerank API improves the accuracy of search systems by re-evaluating the relevance of documents retrieved from an initial search (like vector lookup). It uses a "Cross-Encoder" approach to jointly process the query and each document for superior ranking precision.

Base URL

https://llm.siraya.ai/v1/rerank

How it Works

1. Retrieval: Fetch a candidate list of documents (e.g., top 100) using embeddings or keyword search.
2. Reranking: Send the query and candidates to the Rerank API.
3. Result: Receive the documents sorted by their actual semantic relevance to the query.

Example Request

PythoncURL

import requests

url = "https://llm.siraya.ai/v1/rerank"
headers = {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
}

data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital of Nevada.",
        "Washington, D.C. is the capital of the United States.",
        "Albany is the capital of New York state."
    ]
}

response = requests.post(url, headers=headers, json=data)
results = response.json()["results"]

for res in results:
    print(f"Rank: {res['index']}, Score: {res['relevance_score']}")

curl https://llm.siraya.ai/v1/rerank \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital of Nevada.",
        "Washington, D.C. is the capital of the United States.",
        "Albany is the capital of New York state."
    ]
  }'

Request Parameters

The Rerank API is Cohere-compatible.

Parameter	Type	Description
model	string	Required. The ID of the reranker model (e.g., voyage-rerank-2.5, jina-reranker-v2-base-multilingual).
query	string	Required. The search query.
documents	array	Required. Items are either plain strings or {"text": "..."} objects.
top_n	integer	(Optional) Return only the top N results.
return_documents	boolean	(Optional) Include the document text in each result.
max_tokens_per_doc	integer	(Optional) Truncate each document to this many tokens before scoring.
rank_fields	array	(Optional) Fields to rank on, for structured-document reranking.

Response

{
    "id": "rerank-...",
    "results": [
        { "index": 1, "relevance_score": 0.98, "document": { "text": "Washington, D.C. is the capital of the United States." } }
    ],
    "meta": { "billed_units": { "search_units": 1 } }
}

Field	Type	Description
results[].index	integer	Index into the original documents array.
results[].relevance_score	float	Relevance score (higher = more relevant).
results[].document	object	Present only when return_documents=true.
meta.billed_units	object	search_units (Cohere semantics, 1 per call); input_tokens/total_tokens are populated when the upstream bills by tokens.

Tips for Better Performance

• Structured Data: If your documents contain structured fields, formatting them as YAML strings often yields better reranking results than plain JSON or flat text.
• Max Documents: Most rerankers perform best when given between 50 and 100 candidate documents.

Supported providers include Voyage AI, Jina, and more. See the Models Directory for a full list.