Rerank Documents

POST /v1/rerank Models: Rerank View .md

Rank documents by relevance to a query. Requests and responses follow OpenRouter's rerank schema whichever engine serves the model.

Body

application/json

OpenRouter's rerank request. Every model receives only the query and plain-text documents; top_n and the document echo are applied by the API so they behave the same on every model. OpenRouter's provider, user, session_id and trace and Cohere v2's max_tokens_per_doc and priority are accepted and ignored.

model string required

The rerank model to use.
query string required

The search query to rank the documents against.

at least 1 characters
documents array of (string or object)s required

The documents to rank, as plain strings or objects with a text field. Image documents are rejected.

at least 1 items
One of 2
- string
- object
  - text string required
top_n integer

Return only the highest scoring top_n results. All results are returned when omitted.

range 1–100
return_documents boolean

Extension to OpenRouter's schema. Set false to omit document from each result.

default true

Responses

application/json · rerank-response-payload

4 fields

id string required

Identifier for this rerank response.
model string required

The model that ranked the documents.
results array of objects required

One entry per returned document, sorted by relevance_score, highest first.
3 fields
- index integer required
  
  Position of the document in the request's documents list.
- relevance_score number (double) required
  
  The model's own score, passed through unchanged. Higher is more relevant, but the scale is model specific: bge-reranker-v2-m3 scores between 0 and 1, while the Vultron Retriever models use an unbounded scale. Compare scores within one model, not across models.
- document object
  
  The ranked document as {text}. Omitted when return_documents is false.
  1 field
  - text string
usage object required
1 field
- total_tokens integer
  
  Tokens the model processed across every query and document pair. This is the billed input token count.

curl https://api.vultrinference.com/v1/rerank \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is the capital of France?",
    "documents": [
      "Berlin is the capital of Germany.",
      "Paris is the capital of France."
    ],
    "top_n": 1
  }'

import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "What is the capital of France?",
        "documents": [
            "Berlin is the capital of Germany.",
            "Paris is the capital of France.",
        ],
        "top_n": 1,
    },
)
print(response.json())

const response = await fetch("https://api.vultrinference.com/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "bge-reranker-v2-m3",
    "query": "What is the capital of France?",
    "documents": [
      "Berlin is the capital of Germany.",
      "Paris is the capital of France."
    ],
    "top_n": 1
  }),
});
console.log(await response.json());

Response · 200

{
    "id": "rerank-3f1c9a0d2b7e4c6a8d5e1f02",
    "model": "bge-reranker-v2-m3",
    "results": [
        {
            "index": 1,
            "relevance_score": 0.9998499,
            "document": {
                "text": "Paris is the capital of France."
            }
        }
    ],
    "usage": {
        "total_tokens": 36
    }
}