> ## Documentation Index
> Fetch the complete documentation index at: https://kiosapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  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.
</Tip>

## Request

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

### Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your API key in the format `Bearer sk-xxx`.
</ParamField>

### Request Body

<ParamField body="model" type="string" required>
  The rerank model to use. Example: `gte-rerank-v2`.
</ParamField>

<ParamField body="query" type="string" required>
  The query text to rank the documents against.
</ParamField>

<ParamField body="documents" type="array" required>
  An array of candidate document strings to be scored and reordered.
</ParamField>

<ParamField body="top_n" type="integer">
  The maximum number of top-ranked documents to return. Defaults to returning all documents.
</ParamField>

<ParamField body="return_documents" type="boolean">
  When `true`, the original document text is included in each result object. Defaults to `false`.
</ParamField>

### Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>
</Tabs>

## Response

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

```json theme={null}
{
  "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

<ResponseField name="results" type="array">
  An array of ranked result objects, sorted from most to least relevant.

  <Expandable title="results[] fields">
    <ResponseField name="results[].document.text" type="string">
      The original text of the document. Only present when `return_documents` is `true` in the request.
    </ResponseField>

    <ResponseField name="results[].index" type="integer">
      The zero-based index of this document in the original `documents` input array. Use this to map results back to your source data.
    </ResponseField>

    <ResponseField name="results[].relevance_score" type="number">
      A score between `0` and `1` indicating how relevant the document is to the query. Higher values indicate stronger relevance.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  The number of tokens consumed by the query and documents.
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  Total tokens processed for this request.
</ResponseField>