> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inquantum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank

> Score candidate documents against a query with a provider-neutral reranking contract.

## Endpoint

```text theme={null}
POST https://api.inquantum.ai/v1/rerank
```

## Request

| Field              | Type                   | Required | Description                                                          |
| ------------------ | ---------------------- | -------- | -------------------------------------------------------------------- |
| `model`            | string                 | Yes      | Exact rerank model ID from the model registry.                       |
| `query`            | string                 | Yes      | Non-empty query used to rank the documents.                          |
| `documents`        | string\[] or object\[] | Yes      | Non-empty candidates. Objects must contain a non-empty `text` field. |
| `top_n`            | integer                | No       | Maximum number of results to return.                                 |
| `return_documents` | boolean                | No       | Include document text in normalized results.                         |
| `task`             | string                 | No       | Optional task instruction for providers that support it.             |

```bash theme={null}
curl https://api.inquantum.ai/v1/rerank \
  -H "Authorization: Bearer $PLANCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fireworks/qwen3-reranker-8b",
    "query": "How do I reset my API key?",
    "documents": [
      "Open the API Keys page and select Rotate key.",
      "Invoices are available from the Billing page."
    ],
    "top_n": 1,
    "return_documents": true
  }'
```

## Response

```json theme={null}
{
  "id": "request-id",
  "object": "list",
  "model": "accounts/fireworks/models/qwen3-reranker-8b",
  "provider": "fireworks",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.98,
      "document": {
        "text": "Open the API Keys page and select Rotate key."
      }
    }
  ],
  "usage": {
    "input_tokens": 24
  }
}
```

See the [Reranking guide](/gateway/reranking) for provider selection, BYOK behavior, and tracking.