Rerank

POST /v3/rerank scores a list of documents against a query and returns the most relevant first. Use it after retrieving candidate passages, then pass the highest-ranked results into your model’s context. Authenticate with a project API key. Reranking requires a paid plan.

Rerank documents

Send a model, a query, and up to 1,000 document strings. Set top_n to limit the results and return_documents to include their text.

curl https://api.opper.ai/v3/rerank \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "How do I reset my password?",
    "documents": [
      "Billing and invoices",
      "Use the forgot-password link to reset your password",
      "Release notes"
    ],
    "top_n": 1,
    "return_documents": true
  }'

import os
import requests

response = requests.post(
    "https://api.opper.ai/v3/rerank",
    headers={"Authorization": f"Bearer {os.environ['OPPER_API_KEY']}"},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "How do I reset my password?",
        "documents": [
            "Billing and invoices",
            "Use the forgot-password link to reset your password",
            "Release notes",
        ],
        "top_n": 1,
        "return_documents": True,
    },
    timeout=65,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["index"], result["relevance_score"], result["document"]["text"])

const response = await fetch("https://api.opper.ai/v3/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "bge-reranker-v2-m3",
    query: "How do I reset my password?",
    documents: [
      "Billing and invoices",
      "Use the forgot-password link to reset your password",
      "Release notes",
    ],
    top_n: 1,
    return_documents: true,
  }),
});
if (!response.ok) throw new Error(await response.text());
const { results } = await response.json();
for (const result of results) {
  console.log(result.index, result.relevance_score, result.document.text);
}

The response contains results, a generation id, the model endpoint that served the request, and usage. Each result’s index points to its original position in your documents array, even after sorting. For this example, the password-reset passage at index 1 ranks first.

Field	Behavior
`model`	Required. A rerank model name or a fully qualified endpoint ID.
`query`	Required. A nonblank search query.
`documents`	Required. An array of 1–1,000 strings. Providers may impose additional document-length limits.
`top_n`	Optional integer, at least 1. Omit to return all documents.
`return_documents`	Defaults to `false`. Set to `true` to include `results[].document.text`; otherwise use `results[].index` to retrieve the original text yourself.
`top_k`	Compatibility alias for `top_n`. Zero means unspecified. If both fields have positive values, they must match; conflicting values return `400`.

Choose a model

List available rerank models with GET /v3/models?type=rerank:

curl "https://api.opper.ai/v3/models?type=rerank" \
  -H "Authorization: Bearer $OPPER_API_KEY"

A bare name, such as bge-reranker-v2-m3 or rerank-v3.5, selects from that model’s pooled endpoints. If an endpoint fails and another eligible endpoint exists, Opper tries the next one. A fully qualified ID, such as berget/bge-reranker-v2-m3 or aws/cohere/rerank-v3.5, pins one endpoint and does not fall back. The project’s model access rules and provider entitlements apply to every candidate, including fallback endpoints. The response’s model identifies the endpoint that answered.

Usage and cost

usage.total_tokens contains the provider’s reported token count. Rerank tokens are recorded as input tokens; no output text tokens are generated. Providers that do not report tokens return 0, which does not mean the call is free. Billing follows the selected endpoint’s catalog price: per input token for Berget BGE, or per call for Bedrock Cohere. usage.cost and the X-Generation-Cost response header report the cost in USD. A successful request is billed for the endpoint that served it. Limiting the returned results with top_n does not limit the candidate documents sent for scoring.

Errors

Status	Meaning
`400`	Invalid input, an unknown or wrong-type model, or conflicting `top_n` and `top_k` values.
`401`	Missing or invalid project API key.
`402`	Reranking is unavailable on the free plan, or billing access is blocked.
`403`	Model access rules or a required provider agreement prevent the request.
`429`	The upstream provider rate-limited the request and no fallback succeeded.
`502`	An upstream service failure prevented completion.
`504`	The request timed out.

Use the rerank URL directly: https://api.opper.ai/v3/rerank. The /v3/compat base URL used for chat completions does not expose a rerank route. See the API reference for the complete request and response schema.

Get started

Platform

Build

Observe & Control

Integrations

Tutorials

Tooling

Rerank documents

Choose a model

Usage and cost

Errors

​Rerank documents

​Choose a model

​Usage and cost

​Errors

Rerank documents

Choose a model

Usage and cost

Errors