Cohere Rerank

The Cohere Rerank API ranks candidate documents by relevance to a query. Its core request fields are similar to Jina Rerank, with additional support for X-Client-Name and max_tokens_per_doc. The response includes source indexes, relevance scores, a request ID, API version data, and billing metadata.

POST/v1/rerank

Calculate the candidate document relevance score based on the query text and return the ranking result from high to low relevance. Core request fields are basically consistent with Jina Rerank, with additional support for X-Client-Name and max_tokens_per_doc; Successful responses include result index, relevance score, request identifier, API version, and billing metadata. To achieve more stable sorting results, queries should be clear and specific, and documents should be concise and semantic. Long documents will be truncated according to max_tokens_per_doc; It is recommended to request no more than 1,000 documents per request, and structured data should be converted to YAML strings

Authorization

bearerAuth

AuthorizationBearer <token>

Use Bearer your-api-key in the Authorization Header.

In: header

Header Parameters

X-Client-Name?string

Name of the project to be requested.

Request Body

application/json

Cohere-style document reranking request parameters.

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Reranking model ID. Use a model visible to the current API key that supports the Cohere Rerank format.

Length1 <= length

query*string

Query text for comparison with candidate documents. It is recommended to use clear and specific queries to avoid overly vague or broad expressions.

Length1 <= length

documents*array<string>

List of texts to be compared with queries. It is recommended to request no more than 1,000 documents at a time; Long documents are truncated by max_tokens_per_doc, and structured data is recommended to be converted to YAML strings.

Items1 <= items

top_n?integer

Limits the number of reranked results returned. When omitted, all results are returned. Set this field when only a small result set is needed.

max_tokens_per_doc?integer

The maximum number of tokens per document can participate in resorting; content exceeding this number will be truncated.

Default4096

Response Body

`application/json`

curl -X POST "https://example.com/v1/rerank" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "query": "What is the capital of the United States?",    "documents": [      "The capital of Nevada is Carson City.",      "The Northern Mariana Islands are a group of islands in the Pacific Ocean, with Saipan as its capital.",      "Washington, D.C. (also known as Washington or D.C., officially the District of Columbia) is the capital of the United States.",      "In English grammar, capitalization is used at the beginning of words. English usage differs from other languages.",      "The death penalty existed in the United States before it became a nation. As of 2017, the death penalty was legal in 30 out of 50 states."    ],    "top_n": 3  }'

{
  "results": [
    {
      "index": 2,
      "relevance_score": 0.999071
    },
    {
      "index": 0,
      "relevance_score": 0.32713068
    },
    {
      "index": 1,
      "relevance_score": 0.1867867
    }
  ],
  "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
  "meta": {
    "api_version": {
      "version": "2",
      "is_experimental": false
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

Authorization

Header Parameters

Request Body

Response Body

200application/json

400

401

403

404

422

429

500

503

`application/json`