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

# Rerank

> Rerank a list of documents by relevance to a query, returning results sorted by relevance.

## Headers

**Authorization** `string` *required*

Bearer token authentication. Format: `Authorization: Bearer sk-xxxxxx`

## Body

Format: `application/json`

**model** `string` *required*

Model ID.

**query** `string` *required*

Query text.

**documents** `(string | object)[]` *required*

List of documents to rerank.

**top\_n** `integer`

Return the top N results.

**return\_documents** `boolean` (default: false)

Whether to return the original document content in the results.

## Response

### 200 Successfully reranked

Format: `application/json`

**id** `string`

Rerank task ID.

**results** `object[]`

List of reranking results.

**Properties**

**index** `integer`

Original document index.

**relevance\_score** `number`

Relevance score.

**document** `object`

Original document content (returned only when `return_documents` is `true`).

**meta** `object`

Metadata.

```bash cURL theme={"dark"}
curl -X POST "https://t.ato2.nodesms.com/v1/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v2.0",
    "query": "What is the capital of the United States?",
    "documents": [
      "Carson City is the capital city of the American state of Nevada.",
      "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
      "Washington, D.C. is the capital of the United States.",
      "Capital punishment has existed in the United States since before it was a country."
    ],
    "top_n": 3
  }'
```

```python Python theme={"dark"}
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxx",
    base_url="https://t.ato2.nodesms.com/v1"
)

response = client.post(
    "/rerank",
    json={
        "model": "rerank-english-v2.0",
        "query": "What is the capital of the United States?",
        "documents": [
            "Carson City is the capital city of the American state of Nevada.",
            "Washington, D.C. is the capital of the United States."
        ],
        "top_n": 2
    }
)
print(response.json())
```

```json 200 theme={"dark"}
{
  "id": "string",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.9871293,
      "document": {}
    },
    {
      "index": 1,
      "relevance_score": 0.3456789,
      "document": {}
    }
  ],
  "meta": {}
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.