# Rerank Documents

`POST https://api.vultrinference.com/v1/rerank`

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

## Body (application/json)

- `model` (string, required): The [rerank model](#operation/list-models) 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]
- `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

- `200`: OK (rerank-response-payload)
- `400`: The request body is not a JSON object, top_n is over 100, the model rejected the request, or the input is longer than the model's context length (metadata.error_type context_length_exceeded) (error-payload)
- `401`: The API key is missing, unknown or not active. Send it as Authorization: Bearer <key>. (error-payload)
- `404`: Model not found (error-payload)
- `429`: Rate limit exceeded (error-payload)
- `502`: The model could not be reached or returned an unusable response (error-payload)
- `504`: The model timed out (error-payload)
- `413`: The request body is over 16 MB (error-payload)

## Example

```bash
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
  }'
```

```python
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())
```

```javascript
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());
```