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

# POST /v1/rerank — Document Reranking

> Rerank a list of documents by relevance to a query. Returns scored results sorted from most to least relevant for use in RAG and search pipelines.

The `/v1/rerank` endpoint takes a search query and a list of documents, then returns the documents ordered by their relevance to the query. Each result includes a relevance score you can use to filter or threshold results before passing them to a language model. Reranking is commonly used as a second-stage retrieval step in RAG pipelines to improve the quality of context sent to a model.

## Request parameters

<ParamField body="model" type="string" required>
  The reranking model to use. Use the [list models](/api-reference/models) endpoint to find available reranking model IDs.
</ParamField>

<ParamField body="query" type="string" required>
  The search query against which the documents are ranked.
</ParamField>

<ParamField body="documents" type="string[]" required>
  An array of document strings to rank. Each string is treated as a candidate document. The order of this array determines the `index` values in the response.
</ParamField>

<ParamField body="top_n" type="integer">
  The maximum number of results to return. When omitted, all documents are returned ranked by relevance score.
</ParamField>

## Response fields

<ResponseField name="results" type="array">
  An array of ranked result objects sorted from highest to lowest relevance score.

  <Expandable title="properties">
    <ResponseField name="index" type="integer">
      The zero-based position of this document in the original `documents` input array.
    </ResponseField>

    <ResponseField name="relevance_score" type="number">
      A float between `0` and `1` indicating how relevant the document is to the query. Higher values indicate greater relevance.
    </ResponseField>

    <ResponseField name="document" type="string">
      The document text, as provided in the input array.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request

```bash theme={null}
curl https://tokmodel.com/v1/rerank \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "cohere/rerank-english-v3.0",
    "query": "How do I reset my password?",
    "documents": [
      "To reset your password, click the Forgot Password link on the login page.",
      "Our pricing plans start at $10 per month.",
      "You can update your email address from the Account Settings page.",
      "Password requirements: at least 8 characters, one number, one symbol."
    ],
    "top_n": 2
  }'
```

### Response

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9823,
      "document": "To reset your password, click the Forgot Password link on the login page."
    },
    {
      "index": 3,
      "relevance_score": 0.7541,
      "document": "Password requirements: at least 8 characters, one number, one symbol."
    }
  ]
}
```