Endpoints

Rerank

Scores and reorders documents by relevance to a query. Cohere-compatible.

POST /v1/rerank

curl https://api.pendra.ai/v1/rerank \
  -H "Authorization: Bearer pdr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "How do I rotate an API key?",
    "documents": [
      "Billing is invoiced monthly.",
      "Create a new key, then revoke the old one.",
      "API keys are shown only once at creation."
    ],
    "top_n": 2,
    "return_documents": true
  }'

import requests

resp = requests.post(
    "https://api.pendra.ai/v1/rerank",
    headers={"Authorization": "Bearer pdr_sk_..."},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "How do I rotate an API key?",
        "documents": [
            "Billing is invoiced monthly.",
            "Create a new key, then revoke the old one.",
            "API keys are shown only once at creation.",
        ],
        "top_n": 2,
    },
)
print(resp.json()["results"])

const resp = await fetch('https://api.pendra.ai/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pdr_sk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bge-reranker-v2-m3',
    query: 'How do I rotate an API key?',
    documents: [
      'Billing is invoiced monthly.',
      'Create a new key, then revoke the old one.',
      'API keys are shown only once at creation.',
    ],
    top_n: 2,
  }),
});
console.log((await resp.json()).results);

200

{
  "id": "f3a1c0d2-1b4e-4c9a-9e8d-7a6b5c4d3e2f",
  "results": [
    {
      "index": 1,
      "relevance_score": 8.734,
      "document": { "text": "Create a new key, then revoke the old one." }
    },
    {
      "index": 0,
      "relevance_score": -4.219,
      "document": { "text": "Billing is invoiced monthly." }
    }
  ],
  "meta": {
    "api_version": { "version": "1" }
  }
}

New to reranking? Start with the Reranking guide. This page is the field-by-field reference.

The endpoint is also available at /api/v1/rerank. The request and response follow the Cohere Rerank shape, so a Cohere-style base URL works unchanged.

Body application/json

model string required

Rerank model ID. List the options at /models?type=rerank.

query string required

The search query each document is scored against.

documents string[] required

The list of documents to score. Must contain at least one string.

top_n integer

Return only the top_n most relevant results. Must be 1 or greater when provided. Omit to return all documents, still sorted by relevance.

return_documents boolean default: false

When true, each result echoes the original document text under document.text.

Response

A results array sorted by relevance_score (highest first). Each result carries the index of the document in your original documents list, its relevance_score, and — when return_documents is set — the document text.

Notes

relevance_score is a raw score: higher means more relevant, and scores are only comparable to each other within the same response — they are not normalized to a fixed range.
A reranker reads every query-and-document pair, so cost scales with the number of documents — rerank a shortlist (tens of candidates), not your whole corpus.
Rerank requests appear under Rerank in the console usage view.