Версии API

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

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

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

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

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

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

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

Эти изменения в v1 не делаются: удаление или переименование полей, изменение типа поля, требование нового обязательного параметра, изменение смысла существующих значений. Если такое понадобится, мы выпустим новую версию с отдельным адресом и заранее сообщим об этом и о сроках перехода в журнале изменений.

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

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

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

Все изменения API записываются в журнал изменений. Спецификация openapi.json обновляется вместе с ними.