Create Rerank
curl --request POST \
--url https://api.edenai.run/v3/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"query": "<string>",
"documents": [
"<string>"
],
"tags": {
"client": "acme",
"project": "invoices"
},
"routing": {
"sticky": true,
"allow_fallbacks": true,
"quality_cost": 5,
"allowed_providers": [
"<string>"
],
"zero_data_retention": true,
"ignored_providers": [
"<string>"
],
"order": [
"<string>"
],
"max_price": {
"input": 1,
"output": 1
}
},
"top_n": 1,
"return_documents": false,
"metadata": {},
"extra_headers": {}
}
'import requests
url = "https://api.edenai.run/v3/rerank"
payload = {
"model": "<string>",
"query": "<string>",
"documents": ["<string>"],
"tags": {
"client": "acme",
"project": "invoices"
},
"routing": {
"sticky": True,
"allow_fallbacks": True,
"quality_cost": 5,
"allowed_providers": ["<string>"],
"zero_data_retention": True,
"ignored_providers": ["<string>"],
"order": ["<string>"],
"max_price": {
"input": 1,
"output": 1
}
},
"top_n": 1,
"return_documents": False,
"metadata": {},
"extra_headers": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
query: '<string>',
documents: ['<string>'],
tags: {client: 'acme', project: 'invoices'},
routing: {
sticky: true,
allow_fallbacks: true,
quality_cost: 5,
allowed_providers: ['<string>'],
zero_data_retention: true,
ignored_providers: ['<string>'],
order: ['<string>'],
max_price: {input: 1, output: 1}
},
top_n: 1,
return_documents: false,
metadata: {},
extra_headers: {}
})
};
fetch('https://api.edenai.run/v3/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.edenai.run/v3/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'query' => '<string>',
'documents' => [
'<string>'
],
'tags' => [
'client' => 'acme',
'project' => 'invoices'
],
'routing' => [
'sticky' => true,
'allow_fallbacks' => true,
'quality_cost' => 5,
'allowed_providers' => [
'<string>'
],
'zero_data_retention' => true,
'ignored_providers' => [
'<string>'
],
'order' => [
'<string>'
],
'max_price' => [
'input' => 1,
'output' => 1
]
],
'top_n' => 1,
'return_documents' => false,
'metadata' => [
],
'extra_headers' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.edenai.run/v3/rerank"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.edenai.run/v3/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.edenai.run/v3/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}"
response = http.request(request)
puts response.read_body{
"cost": 123,
"provider": "<string>",
"id": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123,
"document": {
"text": "<string>"
}
}
],
"meta": {},
"usage": {
"search_units": 123,
"total_tokens": 123
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Rerank
Create Rerank
Rank documents by relevance to query (Cohere v2 rerank).
POST
/
v3
/
rerank
Create Rerank
curl --request POST \
--url https://api.edenai.run/v3/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"query": "<string>",
"documents": [
"<string>"
],
"tags": {
"client": "acme",
"project": "invoices"
},
"routing": {
"sticky": true,
"allow_fallbacks": true,
"quality_cost": 5,
"allowed_providers": [
"<string>"
],
"zero_data_retention": true,
"ignored_providers": [
"<string>"
],
"order": [
"<string>"
],
"max_price": {
"input": 1,
"output": 1
}
},
"top_n": 1,
"return_documents": false,
"metadata": {},
"extra_headers": {}
}
'import requests
url = "https://api.edenai.run/v3/rerank"
payload = {
"model": "<string>",
"query": "<string>",
"documents": ["<string>"],
"tags": {
"client": "acme",
"project": "invoices"
},
"routing": {
"sticky": True,
"allow_fallbacks": True,
"quality_cost": 5,
"allowed_providers": ["<string>"],
"zero_data_retention": True,
"ignored_providers": ["<string>"],
"order": ["<string>"],
"max_price": {
"input": 1,
"output": 1
}
},
"top_n": 1,
"return_documents": False,
"metadata": {},
"extra_headers": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
query: '<string>',
documents: ['<string>'],
tags: {client: 'acme', project: 'invoices'},
routing: {
sticky: true,
allow_fallbacks: true,
quality_cost: 5,
allowed_providers: ['<string>'],
zero_data_retention: true,
ignored_providers: ['<string>'],
order: ['<string>'],
max_price: {input: 1, output: 1}
},
top_n: 1,
return_documents: false,
metadata: {},
extra_headers: {}
})
};
fetch('https://api.edenai.run/v3/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.edenai.run/v3/rerank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'query' => '<string>',
'documents' => [
'<string>'
],
'tags' => [
'client' => 'acme',
'project' => 'invoices'
],
'routing' => [
'sticky' => true,
'allow_fallbacks' => true,
'quality_cost' => 5,
'allowed_providers' => [
'<string>'
],
'zero_data_retention' => true,
'ignored_providers' => [
'<string>'
],
'order' => [
'<string>'
],
'max_price' => [
'input' => 1,
'output' => 1
]
],
'top_n' => 1,
'return_documents' => false,
'metadata' => [
],
'extra_headers' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.edenai.run/v3/rerank"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.edenai.run/v3/rerank")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.edenai.run/v3/rerank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"query\": \"<string>\",\n \"documents\": [\n \"<string>\"\n ],\n \"tags\": {\n \"client\": \"acme\",\n \"project\": \"invoices\"\n },\n \"routing\": {\n \"sticky\": true,\n \"allow_fallbacks\": true,\n \"quality_cost\": 5,\n \"allowed_providers\": [\n \"<string>\"\n ],\n \"zero_data_retention\": true,\n \"ignored_providers\": [\n \"<string>\"\n ],\n \"order\": [\n \"<string>\"\n ],\n \"max_price\": {\n \"input\": 1,\n \"output\": 1\n }\n },\n \"top_n\": 1,\n \"return_documents\": false,\n \"metadata\": {},\n \"extra_headers\": {}\n}"
response = http.request(request)
puts response.read_body{
"cost": 123,
"provider": "<string>",
"id": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123,
"document": {
"text": "<string>"
}
}
],
"meta": {},
"usage": {
"search_units": 123,
"total_tokens": 123
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Cohere POST /v2/rerank request body, plus Eden extensions.
Unknown top-level fields are forwarded to the provider; connection keys are rejected.
routing is declared so prepare_input reads it validated; with a concrete
'provider/model' only zero_data_retention applies.
Model identifier in 'provider/model' format, e.g. 'cohere/rerank-v3.5'.
The search query to rank the documents against.
Minimum string length:
1The texts to rank, at most 1000.
Required array length:
1 - 1000 elementsUp to 10 key/value labels recorded with this call, for filtering and grouping usage. Merged with the X-EdenAI-Tags header.
Example:
{ "client": "acme", "project": "invoices" }
How to pick between the providers that serve the requested model. Applies when model is a model name with no provider prefix (e.g. 'gpt-5.5'); ignored for a concrete 'provider/model' id, which already names its provider, except zero_data_retention, which holds every model in the request to it. With model='@edenai' the platform chooses the model too: quality_cost steers that choice, and the provider fields apply whenever the chosen model is a provider-less name.
Show child attributes
Show child attributes
Return only the top_n most relevant results. Defaults to all documents.
Required range:
x > 0Echo each ranked document's text in its result under document.text.
Arbitrary metadata attached to the request.
Additional HTTP headers forwarded to the provider API.
Show child attributes
Show child attributes
Response
Successful Response
Cohere-compatible rerank response plus Eden cost and provider.
usage carries the billed units: search_units or total_tokens.
Charge in USD from the row's rates; None when it cannot be computed in full (no row, an unusable rate, or no billable count for a priced unit).
Identifier of the rerank call, as the provider returned it.
Documents ordered by relevance to the query, most relevant first.
Show child attributes
Show child attributes
The provider's own billing metadata, as litellm returned it.
The priced units of the call; both counts are None when the provider reports neither.
Show child attributes
Show child attributes