Rerank

Rerank a list of documents by their relevance to a query. Useful for improving retrieval results from vector search or keyword search.

POST /v1/rerank

Required capability: rerank

Request Body

Parameter	Type	Required	Description
model	string	Yes	Reranking model identifier (e.g. rerank-english-v3.0, rerank-multilingual-v3.0).
query	string	Yes	The search query to rank documents against.
documents	string[]	Yes	Array of document strings to rerank (1-10,000 documents).
top_n	integer	No	Number of top results to return. Defaults to the length of the input documents array.
return_documents	boolean	No	If true, the response includes the document text alongside scores.

Request size limit: 10 MB

Response

{
  "results": [
    {
      "index": 3,
      "relevance_score": 0.9856,
      "document": "Quantum computing uses qubits that can exist in superposition..."
    },
    {
      "index": 0,
      "relevance_score": 0.7234,
      "document": "Classical computers use binary bits..."
    }
  ],
  "model": "rerank-english-v3.0"
}

Response Fields

Field	Type	Description
results	array	Array of reranked results, sorted by relevance score (highest first).
results[].index	integer	Original index of the document in the input array.
results[].relevance_score	number	Relevance score between 0 and 1. Higher is more relevant.
results[].document	string	The document text (only present when return_documents is true).
model	string	The model used for reranking.

Example

curl https://your-gateway.example.com/v1/rerank \
  -H "Authorization: Bearer aigw_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "What is quantum computing?",
    "documents": [
      "Classical computers use binary bits to process information.",
      "The weather forecast predicts rain tomorrow.",
      "Machine learning models require training data.",
      "Quantum computing uses qubits that can exist in superposition states.",
      "The stock market closed higher today."
    ],
    "top_n": 3,
    "return_documents": true
  }'