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

# Cohere Rerank

***

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.znapai.com/v1/rerank' \
  --header 'Authorization: Bearer $ZnapAI_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "cohere-rerank-v4.0-fast",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany.",
      "The Eiffel Tower is located in Paris."
    ]
  }'
  ```

  ```python Cohere SDK (Python) theme={null}
  import cohere

  co = cohere.Client(
      api_key="$ZnapAI_API_KEY",
      base_url="https://api.znapai.com/v1"
  )

  response = co.rerank(
      model="cohere-rerank-v4.0-fast",
      query="What is the capital of France?",
      documents=[
          "Paris is the capital of France.",
          "Berlin is the capital of Germany.",
          "The Eiffel Tower is located in Paris."
      ]
  )

  print(response)
  ```

  ```javascript Cohere SDK (JS) theme={null}
  import { CohereClient } from "cohere-ai";

  const cohere = new CohereClient({
    token: "$ZnapAI_API_KEY",
    environment: "https://api.znapai.com/v1"
  });

  const response = await cohere.rerank({
    model: "cohere-rerank-v4.0-fast",
    query: "What is the capital of France?",
    documents: [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany.",
      "The Eiffel Tower is located in Paris."
    ]
  });

  console.log(response);
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "id": "56df1b8a-22ab-49e8-b6fc-31c79838ca8f",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.8570099
    },
    {
      "index": 2,
      "relevance_score": 0.42403036
    },
    {
      "index": 1,
      "relevance_score": 0.36080432
    }
  ],
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "search_units": 1
    }
  }
}
```

***

## Parameters

<ParamField path="model" type="string" required>
  The name of the model to use for reranking. Supported model: `cohere-rerank-v4.0-fast`.
</ParamField>

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

<ParamField path="documents" type="array" required>
  The list of documents to be reranked. Supports both simple string arrays and structured object arrays.
</ParamField>

<ParamField path="top_n" type="integer">
  The number of most relevant documents to return.
</ParamField>

<ParamField path="rank_fields" type="array of strings">
  Determines which fields in a structured object document are used for ranking. If omitted, the API automatically determines how to rank structured documents.
</ParamField>

<ParamField path="return_documents" type="boolean" default="true">
  If set to `true`, the ranked documents will be included in the response.
</ParamField>

<ParamField path="priority" type="integer">
  Request priority (from 0 to 999). A lower value indicates a higher priority.
</ParamField>

<ParamField path="max_tokens_per_doc" type="integer">
  The maximum number of tokens processed per document before truncation.
</ParamField>

***

## Returns

The response contains a unique ID, ranked results, and API usage metadata.

<ResponseField name="id" type="string">
  A unique identifier for the rerank request.
</ResponseField>

<ResponseField name="results" type="array">
  The ordered list of ranked documents, sorted by relevance score descending.

  <Expandable title="results[]" defaultOpen="true">
    <ResponseField name="index" type="integer">
      The original index of the document in the request array.
    </ResponseField>

    <ResponseField name="relevance_score" type="number">
      A score indicating how relevant the document is to the query.
    </ResponseField>

    <ResponseField name="document" type="object">
      The returned document representation. Always normalized to a single `text` field.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadata containing the API version and billed units.

  <Expandable title="meta" defaultOpen="true">
    <ResponseField name="api_version" type="object">
      The API version information.
    </ResponseField>

    <ResponseField name="billed_units" type="object">
      The billed units for the request.

      <Expandable title="billed_units" defaultOpen="true">
        <ResponseField name="search_units" type="integer">
          The number of search units billed for this request.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Behavior & Validation Notes

### 1. `rank_fields` is Optional

The request succeeds even when `rank_fields` is omitted. The API automatically determines how to rank structured documents.

### 2. `rank_fields` Controls Ranking

Providing specific fields in `rank_fields` (e.g., `["title"]`) restricts the model to only use those fields for calculation, overriding other fields (such as `text`).

### 3. Document Normalization in Response

When `return_documents` is enabled, the API returns a **normalized** document containing **only** the `text` field. Original metadata fields (such as `title`, `author`, `year`, etc.) are stripped out of the response.

### 4. Independence of `rank_fields` and Response Inclusion

Even if ranking is performed on fields like `title`, the returned document in `results.document` will still be normalized to the `text` field.

### 5. Billing based on Search Units

Billing is calculated solely on **search units** (e.g., `billed_units.search_units`). There is no output token cost or separate pricing for input tokens.