curl --request POST \
--url https://api.opper.ai/v3/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"documents": [
"<string>"
],
"model": "<string>",
"query": "<string>"
}
'import requests
url = "https://api.opper.ai/v3/rerank"
payload = {
"documents": ["<string>"],
"model": "<string>",
"query": "<string>"
}
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({documents: ['<string>'], model: '<string>', query: '<string>'})
};
fetch('https://api.opper.ai/v3/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123,
"document": {
"text": "<string>"
}
}
],
"usage": {
"cost": 123,
"total_tokens": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}Rerank documents
Reorder documents by relevance to query and get them back most-relevant first. model, query and documents are required; top_n caps how many results come back (integer >=1; default: all). top_k is a compatibility alias (zero means unspecified); positive values must match when both fields are supplied, and return_documents echoes each document’s text alongside its score. Up to 1000 documents per call. Billed per call or per token depending on the endpoint: usage.cost is what was charged, usage.total_tokens the provider’s count when it reports one.
model accepts either form, and which one you send decides the routing:
- a bare model name (e.g.
rerank-v3.5) routes over that model’s pooled endpoints and falls over to the next one when an endpoint fails — the case this matters for is provider rate limits, where one endpoint’s quota is exhausted and another’s is not. - a fully-qualified id (e.g.
aws/cohere/rerank-v3.5) pins that exact endpoint and never falls over.
The response’s model is the endpoint that actually served the call, which for a pooled name is not necessarily the preferred one. List what is available with GET /v3/models?type=rerank.
The project’s Comply model allowlist applies to every endpoint a bare name can route to, not only the one you named: an endpoint it forbids is never tried, not even as a fallover target. A pinned id the allowlist forbids, or a pool it empties, is refused with 403 rather than substituted. A provider that requires a signed agreement needs the organization’s grant, as everywhere else: no grant, no call, and never as a fallover target.
curl --request POST \
--url https://api.opper.ai/v3/rerank \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"documents": [
"<string>"
],
"model": "<string>",
"query": "<string>"
}
'import requests
url = "https://api.opper.ai/v3/rerank"
payload = {
"documents": ["<string>"],
"model": "<string>",
"query": "<string>"
}
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({documents: ['<string>'], model: '<string>', query: '<string>'})
};
fetch('https://api.opper.ai/v3/rerank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"results": [
{
"index": 123,
"relevance_score": 123,
"document": {
"text": "<string>"
}
}
],
"usage": {
"cost": 123,
"total_tokens": 123
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}Authorizations
API key authentication. Pass your API key as a Bearer token.
Body
Compatibility alias for top_n. Zero means unspecified. Positive values must match top_n when both are supplied.
x >= 0Maximum number of results. Omit to return all documents.
x >= 1