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

# Rerank documents

> Score a list of documents against a query, so only the best few reach your model.

Reranking sits between retrieval and generation: [embeddings](/api-reference/embeddings) decide what to fetch, a reranker decides which of those results are worth sending to a chat model. The reranking models are listed at [`GET /v1/models?type=reranking`](/api-reference/models-list), with prices.

## Request body

<ParamField body="model" type="string" required>
  A reranking model id, for example `qwen3-reranker-8b`. A model of any other type returns `400` pointing to `GET /v1/models?type=reranking`.
</ParamField>

<ParamField body="query" type="string" required>
  The text to rank the documents against. Must not be empty.
</ParamField>

<ParamField body="documents" type="array" required>
  A non-empty array of strings to rank.
</ParamField>

Other fields in the body are forwarded to the model as sent.

## Response

The body is the model's ranking of your documents, returned as the model produced it with two changes: `model` is the Kyma id you called, and `usage.cost` is added. `usage.prompt_tokens` covers the query and every document.

Responses are not streamed.

## Billing

Input tokens only, at the model's input rate: the query plus every document. Sending a hundred documents costs a hundred documents. `usage.cost` is the price of the call in USD, to 8 decimal places.

## Response headers

| Header | When |
| - | - |
| `X-Kyma-Model` | Always. The model id your request resolved to |
| `X-Kyma-Alias` | When you sent an alias; names it |

## Errors

The body is `{"error": {"message": "...", "type": "..."}}`.

| Code | `type` | Means | What to do |
| - | - | - | - |
| `400` | `invalid_request` | Invalid JSON, `query` or `documents` missing or not strings, or a model that is not a reranker | Fix the request |
| other `4xx` | `invalid_request` | The model rejected the request; the status is the one it returned (a `401`, `402` or `403` from the model is a problem on our side and comes back as `503`) | Check `query` and `documents` |
| `401` | `auth_required` / `invalid_credentials` | Key missing, or unknown or revoked | Check the `Authorization` header |
| `404` | `model_not_found` | Kyma does not serve that id | Fix the model id |
| `405` | `invalid_request` | Method other than `POST` | Use `POST` |
| `413` | `invalid_request` | Body over 25 MB | Split the batch |
| `502` | `server_error` | The answer could not be read | Retry |
| `503` | `server_error` | Reranking is unavailable on our side right now | Retry shortly |

<RequestExample>
  ```bash cURL theme={null}
  curl https://kymaapi.com/v1/rerank \
    -H "Authorization: Bearer kyma-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3-reranker-8b",
      "query": "How do I rotate an API key?",
      "documents": [
        "Create a new key, update your clients, then revoke the old one.",
        "Our office is closed on public holidays.",
        "Keys can be revoked from the dashboard at any time."
      ]
    }'
  ```
</RequestExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.