# Версии API

Версия указана в адресе: /v1. Внутри версии ответы меняются только совместимо, а несовместимые изменения выходят в новой версии с отдельным адресом.

## Номера версий

- **Версия API** указана в пути: `https://api.melioralab.io/v1`. Ее же возвращает `GET /v1/me` в поле `api_version`.
- **Версия формата события** указана в каждом событии в поле `api_version`, сейчас `2026-10-18`. Она меняется, если меняется состав полей события. Значение совпадает с версией формата тех же событий в вебхуках кабинета.

## Совместимые изменения

Эти изменения могут появиться в v1 без новой версии:

- новые маршруты;
- новые необязательные параметры запроса;
- новые поля в ответах и во вложенных объектах;
- новые типы событий в ленте;
- новые коды ошибок с уже существующими HTTP-статусами;
- изменение текста `detail` в ошибках.

## Несовместимые изменения

Эти изменения в v1 не делаются: удаление или переименование полей, изменение типа поля, требование нового обязательного параметра, изменение смысла существующих значений. Если такое понадобится, мы выпустим новую версию с отдельным адресом и заранее сообщим об этом и о сроках перехода в [журнале изменений](https://docs.melioralab.io/changelog/).

## Как писать устойчивый клиент

- **Пропускайте неизвестные поля** в ответах, не падайте на них.
- **Обрабатывайте неизвестное значение** перечисления как `unknown`. Мы стараемся не расширять перечисления v1, но такой код ничего не стоит.
- **Пропускайте события незнакомого типа**, но сохраняйте курсор страницы, на которой они пришли.
- **Обрабатывайте незнакомый код ошибки** по HTTP-статусу.
- **Не разбирайте формат идентификаторов** и курсоров: `id` сообщения и `next_cursor` непрозрачны.

## Журнал изменений

Все изменения API записываются в [журнал изменений](https://docs.melioralab.io/changelog/). Спецификация [openapi.json](https://docs.melioralab.io/openapi.json) обновляется вместе с ними.