Amanai Docs

Rerank

Reorder retrieved documents by semantic relevance to a query.

Overview

Use POST /v1/rerank after an initial keyword or vector search. The endpoint scores every submitted candidate against the query and returns the most relevant document indexes in descending order.

Typical retrieval flow. Retrieve a broad candidate set with Embeddings, then rerank the best candidates before placing them in an LLM context.

Model

Model	Capability	Candidate limit
BGE Reranker Base `amanai/bge-reranker-base`	Query-document relevance ranking	Up to 100 documents
Voyage rerank-3 `amanai/voyage-rerank-3`	Query-document relevance ranking	Up to 100 documents
Voyage rerank-3-lite `amanai/voyage-rerank-3-lite`	Query-document relevance ranking	Up to 100 documents
Voyage rerank-2.5 `amanai/voyage-rerank-2.5`	Query-document relevance ranking	Up to 100 documents
Voyage rerank-2.5-lite `amanai/voyage-rerank-2.5-lite`	Query-document relevance ranking	Up to 100 documents

Discover rerank models available to your key with GET /v1/models?type=rerank.

Parameters

Field	Type	Rules
`model`	string	Optional; defaults to `amanai/bge-reranker-base`.
`query`	string	Required, non-empty, up to 2,048 characters.
`documents`	string[]	Required; 1–100 documents, up to 8,192 characters each.
`top_n`	integer	Optional; 1 through the number of documents. Defaults to all documents.

Request

bash

curl https://api.amanai.dev/v1/rerank \
  -H "Authorization: Bearer $AMANAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amanai/bge-reranker-base",
    "query": "best way to learn Indonesian",
    "documents": [
      "Practice with native speakers every day.",
      "A guide to baking sourdough bread.",
      "Build vocabulary with spaced repetition."
    ],
    "top_n": 2
  }'

Response

bash

{
  "object": "list",
  "model": "amanai/bge-reranker-base",
  "results": [
    {"index": 0, "relevance_score": 0.94},
    {"index": 2, "relevance_score": 0.87}
  ]
}

Each result's index points back to the corresponding entry in the submitted documents array. Evaluate score thresholds on your own data rather than assuming one universal cutoff.

Language guidance. Ranking is strongest when query and documents use the same language. For mixed Indonesian, Malay, and English retrieval, validate quality using representative production examples.

Billing

BGE and Voyage rerank models bill tokens across the query and every submitted document, with a 250-credit minimum. top_n limits returned results, not the submitted input billed. See Billing & pricing.