# Версии API и вывод из эксплуатации (/docs/api/versioning)

> Как Hubris версионирует API, как предупреждает об отключении устаревших эндпоинтов и полей (заголовки Deprecation и Sunset) и за сколько дней.

Интеграцию с Hubris можно строить в расчёте на то, что она не сломается без предупреждения. Ниже — правила, по которым мы меняем API.

## Версия в адресе

Версия API — часть адреса: `https://api.hubris.pw/v1/...`. Внутри `/v1` мы только добавляем: новые эндпоинты, новые необязательные параметры запроса, новые поля ответа. Клиент должен спокойно пропускать незнакомые поля в ответе — это единственное, чего мы от него ждём.

Несовместимое изменение — удаление эндпоинта или поля, смена типа поля, новый обязательный параметр, другой смысл кода ошибки — выходит только в новой версии, `/v2`. Старая версия после этого продолжает работать по правилам вывода из эксплуатации ниже.

## Как мы предупреждаем об отключении

Эндпоинт, поле или версию API мы отключаем **не раньше чем через 90 дней** после объявления. В день объявления:

1. Ответы устаревшего эндпоинта получают заголовки:
   * `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) — момент объявления, например `Deprecation: @1798761600`;
   * `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) — дата отключения, например `Sunset: Thu, 01 Apr 2027 00:00:00 GMT`;
   * `Link` с `rel="deprecation"` — ссылка на запись о замене.
2. В [журнале изменений](/docs/changelog) появляется запись: что устаревает, чем заменить, дата отключения.
3. Владельцы аккаунтов, чьи ключи обращались к устаревшему эндпоинту за последние 30 дней, получают письмо.

До даты из `Sunset` эндпоинт работает как раньше. Проверить, не пользуется ли ваш код чем-то устаревшим, можно по заголовку `Deprecation` в ответах.

## Что сейчас устарело

Отключаемых эндпоинтов нет. Три поля оставлены для совместимости и помечены в справочнике как устаревшие; дата их отключения не назначена:

| Поле                  | Где                                                   | Замена                                  |
| --------------------- | ----------------------------------------------------- | --------------------------------------- |
| `data[].modalities`   | [`GET /v1/models`](/docs/api/models)                  | `output_modalities`                     |
| `daily_limit_kopecks` | [Management API](/docs/api/management), `GET /v1/key` | `limit_kopecks` с `limit_period: "day"` |
| `spent_24h_kopecks`   | [Management API](/docs/api/management)                | `spent_period_kopecks`                  |

Когда дата будет назначена, об этом предупредим по правилам выше — не меньше чем за 90 дней.

## Бета

Метка **бета** у [`/v1/responses`](/docs/api/responses) относится только к составу блоков ответа в `output[]`: туда добавляются новые типы по мере того, как их вводят провайдеры моделей. Это расширение, а не несовместимое изменение, поэтому правила выше на него не распространяются. Авторизация, тарификация и потоковая передача у `/v1/responses` стабильны.