Rerank Documents by Query Relevance — POST /v1/rerank

POST /v1/rerank reorders a list of documents by relevance to a query. Returns ranked results with relevance scores. Supports top_n filtering.

Use the /v1/rerank endpoint to reorder a set of candidate documents by their relevance to a given query. This is especially valuable in retrieval-augmented generation (RAG) pipelines and search systems, where a fast first-stage retriever returns a broad candidate set and a reranker then refines the ordering for precision before passing results to a language model.

For best results, combine reranking with vector search: retrieve candidate documents with an embedding-based similarity search, then pass them to /v1/rerank to surface the most relevant ones at the top.

Request

POST https://kiosapi.com/v1/rerank

Headers

Content-Type · string · required

Must be application/json.

Authorization · string · required

Your API key in the format Bearer sk-xxx.

Request Body

model · string · required

The rerank model to use. Example: gte-rerank-v2.

query · string · required

The query text to rank the documents against.

documents · array · required

An array of candidate document strings to be scored and reordered.

top_n · integer

The maximum number of top-ranked documents to return. Defaults to returning all documents.

return_documents · boolean

When true, the original document text is included in each result object. Defaults to false.

Example Request

cURL

curl https://kiosapi.com/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx" \
  -d '{
    "model": "gte-rerank-v2",
    "query": "What is a text reranking model",
    "documents": [
      "Text reranking models are widely used in search engines and recommendation systems, ranking candidate texts by text relevance",
      "Quantum computing is a frontier field in computational science",
      "The development of pre-trained language models has brought new progress to text reranking models"
    ],
    "return_documents": true,
    "top_n": 5
  }'

Python

import requests

url = "https://kiosapi.com/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxx"
}
data = {
    "model": "gte-rerank-v2",
    "query": "What is a text reranking model",
    "documents": [
        "Text reranking models are widely used in search engines",
        "Quantum computing is a frontier field",
        "Pre-trained models brought progress to reranking"
    ],
    "return_documents": True,
    "top_n": 5
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

for r in result["results"]:
    print(f"Index: {r['index']}, Score: {r['relevance_score']:.4f}")

Response

Results are returned in descending relevance order. Each result includes the original document index and a relevance score between 0 and 1.

{
  "results": [
    {
      "document": {
        "text": "Text reranking models are widely used in search engines and recommendation systems, ranking candidate texts by text relevance"
      },
      "index": 0,
      "relevance_score": 0.9334521178273196
    },
    {
      "document": {
        "text": "The development of pre-trained language models has brought new progress to text reranking models"
      },
      "index": 2,
      "relevance_score": 0.34100082626411193
    },
    {
      "document": {
        "text": "Quantum computing is a frontier field in computational science"
      },
      "index": 1,
      "relevance_score": 0.005814161578735119
    }
  ],
  "usage": {
    "prompt_tokens": 79,
    "total_tokens": 79
  }
}

Response Fields

results · array

An array of ranked result objects, sorted from most to least relevant.

Show results[] fields

results[].document.text · string

The original text of the document. Only present when return_documents is true in the request.

results[].index · integer

The zero-based index of this document in the original documents input array. Use this to map results back to your source data.

results[].relevance_score · number

A score between 0 and 1 indicating how relevant the document is to the query. Higher values indicate stronger relevance.

usage.prompt_tokens · integer

The number of tokens consumed by the query and documents.

usage.total_tokens · integer

Total tokens processed for this request.