Rerank API (v2)

POST/v2/rerankRerank API (v2)

This endpoint takes in a query and a list of texts and produces an ordered array with each text assigned a relevance score.

Parameters

X-Client-Namestringheader

The name of the project that is making the request.

Request body

application/json

object

documentsarray of stringrequired

A list of texts that will be compared to the `query`. For optimal performance we recommend against sending more than 1,000 documents in a single request. **Note**: long documents will automatically be truncated to the value of `max_tokens_per_doc`. **Note**: structured data should be formatted as YAML strings for best performance.

Show child attributes

max_tokens_per_docinteger

Defaults to `4096`. Long documents will be automatically truncated to the specified number of tokens.

modelstringrequired

The identifier of the model to use, eg `rerank-v3.5`.

priorityinteger

Controls how early the request is handled. Lower numbers indicate higher priority (default: 0, the highest). When the system is under load, higher-priority requests are processed first and are the least likely to be dropped.

default 0 · maximum 999 · minimum 0

querystringrequired

The search query

top_ninteger

Limits the number of returned rerank results to the specified value. If not passed, all the rerank results will be returned.

minimum 1

Example request

{
  "documents": [
    "string"
  ],
  "max_tokens_per_doc": 0,
  "model": "string",
  "priority": 0,
  "query": "string",
  "top_n": 0
}

Responses

object

idstring

metaobject

Show child attributes

api_versionobject

Show child attributes

is_deprecatedboolean

is_experimentalboolean

versionstringrequired

billed_unitsobject

Show child attributes

classificationsnumber

The number of billed classifications units.

image_tokensnumber

The number of billed image tokens.

imagesnumber

The number of billed images.

input_tokensnumber

The number of billed input tokens.

output_tokensnumber

The number of billed output tokens.

pagesnumber

The number of billed pages parsed.

search_unitsnumber

The number of billed search units.

cached_tokensnumber

The number of prompt tokens that hit the inference cache.

tokensobject

Show child attributes

input_tokensnumber

The number of tokens used as input to the model.

output_tokensnumber

The number of tokens produced by the model.

warningsarray of string

Show child attributes

resultsarray of objectrequired

An ordered list of ranked documents

Show child attributes

Show array items

indexintegerrequired

Corresponds to the index in the original list of documents to which the ranked document belongs. (i.e. if the first value in the `results` object has an `index` value of 3, it means in the list of documents passed in, the document at `index=3` had the highest relevance)

relevance_scorenumber · floatrequired

Relevance scores are normalized to be in the range `[0, 1]`. Scores close to `1` indicate a high relevance to the query, and scores closer to `0` indicate low relevance. It is not accurate to assume a score of 0.9 means the document is 2x more relevant than a document with a score of 0.45

Example response

{
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "results": [
    {
      "index": 0,
      "relevance_score": 0
    }
  ]
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

Examples

X-Client-Nameheader parameter

curl -X POST 'https://api.cohere.com/v2/rerank' \
  -H 'Content-Type: application/json' \
  -d '{"documents":["string"],"max_tokens_per_doc":0,"model":"string","priority":0,"query":"string","top_n":0}'

const response = await fetch('https://api.cohere.com/v2/rerank', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"documents":["string"],"max_tokens_per_doc":0,"model":"string","priority":0,"query":"string","top_n":0}),
});
const data = await response.json();

const response = await fetch('https://api.cohere.com/v2/rerank', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"documents\":[\"string\"],\"max_tokens_per_doc\":0,\"model\":\"string\",\"priority\":0,\"query\":\"string\",\"top_n\":0}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.cohere.com/v2/rerank",
    headers={"Content-Type": "application/json"},
    data='{"documents":["string"],"max_tokens_per_doc":0,"model":"string","priority":0,"query":"string","top_n":0}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"documents":["string"],"max_tokens_per_doc":0,"model":"string","priority":0,"query":"string","top_n":0}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.cohere.com/v2/rerank", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.cohere.com/v2/rerank");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"documents\":[\"string\"],\"max_tokens_per_doc\":0,\"model\":\"string\",\"priority\":0,\"query\":\"string\",\"top_n\":0}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.cohere.com/v2/rerank"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"documents\":[\"string\"],\"max_tokens_per_doc\":0,\"model\":\"string\",\"priority\":0,\"query\":\"string\",\"top_n\":0}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.cohere.com/v2/rerank")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"documents\":[\"string\"],\"max_tokens_per_doc\":0,\"model\":\"string\",\"priority\":0,\"query\":\"string\",\"top_n\":0}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cohere.com/v2/rerank");
request.Content = new StringContent("{\"documents\":[\"string\"],\"max_tokens_per_doc\":0,\"model\":\"string\",\"priority\":0,\"query\":\"string\",\"top_n\":0}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "results": [
    {
      "index": 0,
      "relevance_score": 0
    }
  ]
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

Search documentation

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations

Rerank API (v2)

Parameters

Request body

Responses

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations