POST/v1/rerank

Rerank

Rerank documents against a query by relevance.

Cohere/Jina-style rerank body, typically served by reranker models (e.g. bge-reranker).

Rerank aliases are listed by GET /v1/models with pricing.unit: "document" (prompt is the price per document).

Request body

Field	Type	Required	Notes
`model`	string	yes	A rerank alias.
`query`	string	yes	The search query.
`documents`	array	yes	Strings, or objects with a `text` field.
`top_n`	integer	no	Return only the top N results (≥ 1).
`return_documents`	boolean	no	Include the document text in each result (default `false`).

Code sample

curl https://api.<domain>/v1/rerank \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker",
    "query": "What is the capital of the United States?",
    "documents": [
      "Carson City is the capital city of Nevada.",
      "Washington, D.C. is the capital of the United States.",
      "The capital of Portugal is Lisbon."
    ],
    "top_n": 2
  }'

The OpenAI SDK has no typed rerank method — use its generic request escape hatch (client.post), which targets the same base URL and auth:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.<domain>/v1",
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

resp = client.post(
    "/rerank",
    body={
        "model": "bge-reranker",
        "query": "What is the capital of the United States?",
        "documents": [
            "Carson City is the capital city of Nevada.",
            "Washington, D.C. is the capital of the United States.",
            "The capital of Portugal is Lisbon.",
        ],
        "top_n": 2,
    },
    cast_to=object,
)
print(resp["results"][0]["index"])

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.<domain>/v1',
  apiKey: process.env.TOKENFACTORY_API_KEY,
});

// No typed rerank resource — use the generic post escape hatch.
const resp = await client.post('/rerank', {
  body: {
    model: 'bge-reranker',
    query: 'What is the capital of the United States?',
    documents: [
      'Carson City is the capital city of Nevada.',
      'Washington, D.C. is the capital of the United States.',
      'The capital of Portugal is Lisbon.',
    ],
    top_n: 2,
  },
});
console.log(resp.results[0]);

Response

{
  "id": "rr-1",
  "model": "bge-reranker",
  "results": [
    { "index": 1, "relevance_score": 0.91 },
    { "index": 0, "relevance_score": 0.12 }
  ],
  "usage": { "total_tokens": 40 },
  "provider_metadata": { "provider": "vllm-staging", "actual_model": "BAAI/bge-reranker-v2-m3" }
}

Guaranteed fields: results[].{index, relevance_score, document?}, model (your alias), usage{total_tokens} (only total_tokens survives the strip-list), and provider_metadata. Results are ordered most-relevant first; index refers to the position in your input documents array.

Errors

Standard error surface — see Errors.