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

# POST /v1/rerank — rank documents by query relevance

> Rank a list of documents by relevance to a query using POST /v1/rerank. Compatible with Cohere and Jina rerank API formats. Supported providers: Cohere, Jina.

The `/v1/rerank` endpoint takes a query string and a list of candidate documents, and returns them sorted by relevance to the query. Reranking is typically used as a second-pass filter after a fast initial retrieval step — for example, after a vector similarity search in a RAG pipeline — to improve the quality of the top results passed to a language model.

Anyone's rerank endpoint is compatible with both the Cohere Rerank API format and the Jina Rerank API format.

***

## POST /v1/rerank

### Request body

<ParamField body="model" type="string" required>
  The reranking model to use. For example, `rerank-english-v3.0` (Cohere) or `jina-reranker-v2-base-multilingual` (Jina). The available models depend on your configured channels.
</ParamField>

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

<ParamField body="documents" type="string[] | object[]" required>
  The list of documents to rank. Each element can be a plain string, or an object with a `text` field containing the document text.
</ParamField>

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

<ParamField body="return_documents" type="boolean">
  If `true`, each result includes the original document text in addition to the index and relevance score. Defaults to `false`.
</ParamField>

<ParamField body="max_chunk_per_doc" type="integer">
  Maximum number of chunks per document when the provider splits long documents internally.
</ParamField>

<ParamField body="overlap_tokens" type="integer">
  Number of overlapping tokens between chunks when the provider splits long documents.
</ParamField>

### Response

<ResponseField name="results" type="object[]">
  Ranked list of document results, ordered from most to least relevant.

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

    <ResponseField name="relevance_score" type="number">
      A score between `0.0` and `1.0` indicating how relevant this document is to the query. Higher is more relevant.
    </ResponseField>

    <ResponseField name="document" type="object">
      The original document, only present when `return_documents` is `true`.

      <Expandable title="document properties">
        <ResponseField name="text" type="string">
          The document text.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage for the request.

  <Expandable title="usage properties">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens consumed by the query and documents.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens processed.
    </ResponseField>
  </Expandable>
</ResponseField>

***

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.anyone.ai/v1/rerank \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "rerank-english-v3.0",
      "query": "What is the capital of France?",
      "documents": [
        "Paris is the capital and largest city of France.",
        "The Eiffel Tower is located in Paris.",
        "Berlin is the capital of Germany.",
        "France has a population of over 67 million."
      ],
      "top_n": 2,
      "return_documents": true
    }'
  ```

  ```python python theme={null}
  import httpx

  response = httpx.post(
      "https://api.anyone.ai/v1/rerank",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={
          "model": "rerank-english-v3.0",
          "query": "What is the capital of France?",
          "documents": [
              "Paris is the capital and largest city of France.",
              "The Eiffel Tower is located in Paris.",
              "Berlin is the capital of Germany.",
              "France has a population of over 67 million.",
          ],
          "top_n": 2,
          "return_documents": True,
      },
  )

  for result in response.json()["results"]:
      print(result["index"], result["relevance_score"])
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9921,
      "document": { "text": "Paris is the capital and largest city of France." }
    },
    {
      "index": 1,
      "relevance_score": 0.4103,
      "document": { "text": "The Eiffel Tower is located in Paris." }
    }
  ],
  "usage": {
    "prompt_tokens": 62,
    "total_tokens": 62
  }
}
```

***

## Supported providers

| Provider   | Example models                                                   |
| ---------- | ---------------------------------------------------------------- |
| **Cohere** | `rerank-english-v3.0`, `rerank-multilingual-v3.0`                |
| **Jina**   | `jina-reranker-v2-base-multilingual`, `jina-reranker-v1-base-en` |