# Ранжирование документов

> Требуемое право: text.

`POST https://api.kvantora.ai/v1/rerank`

Требуемое право: text. Упорядочивает документы по релевантности запросу. Синхронный ответ, как у текстовых операций: оценка стоимости и резерв создаются при приёме, итоговая сумма — после ответа. Неизвестные поля и неподдерживаемые формы отклоняются до резервирования. Не более 1 000 документов, весь запрос — до 1 МиБ. Допустимость операции для модели смотрите в каталоге (availability.operations).

## Параметры

- `Idempotency-Key` (header): Рекомендуется для каждого запроса. Один стабильный ключ на логический запрос; при повторе с тем же телом, тем же credential и endpoint возвращается исходный результат (replay:true) без нового списания. Новый ключ создаёт новый запрос. Если заголовок не передан, сервер подставляет случайный ключ, и повтор после сетевой ошибки будет оплачен как новый запрос.

## Пример запроса

```bash
curl --request POST \
  --url "https://api.kvantora.ai/v1/rerank" \
  --header "Authorization: Bearer $KVANTORA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "<public_api_id>",
  "query": "Как вернуть деньги за заказ?",
  "documents": [
    "Условия возврата средств.",
    "Расписание работы офиса."
  ],
  "top_n": 1
}'
```

## Ответы

- 200: Документы упорядочены
- 202: Исход уточняется; резерв сохраняется
- default: Ошибка проверки, прав, лимита или доступности. Код error.code; результат запроса при неизвестном исходе не следует считать отменённым.