Изменения контракта

Что мы обещаем

Публичный контур — это /v1. Внутри одной версии мы:

• не удаляем маршруты и поля ответов без предварительной пометки об устаревании;
• не меняем тип и смысл существующего поля;
• можем добавлять новые поля в ответы и новые необязательные — в запросы.

Значит, от клиента требуется одно: незнакомые поля игнорировать, а не падать на них. Обновлять клиент ради нового поля не нужно.

Исключение ровно одно, и оно узкое: маршруты возможности, которая никогда не работала в проде — жила за выключенным флагом и вызвать её снаружи было нельзя, — могут исчезнуть без периода устаревания. Держать пометку об устаревании на том, чем невозможно было воспользоваться, значит обещать совместимость с поведением, которого не существовало. Молча такое не происходит: каждое такое удаление попадает в список ниже.

Что уже менялось

2 сентября 2026 — снята диаризация

Разбор записи по говорящим убран из продукта. Он работал только на отдельном воркере с собственными зависимостями, а тот в проде не поднимался: DIARIZATION_ENABLED выключен по умолчанию. Запуск разбора при этом отвечал 415, а остальные маршруты формально отвечали, но пустотой — ни разметки, ни голосовых профилей создать было нечем.

Исчезли:

• POST /v1/objects/{object_id}/diarize
• PATCH /v1/objects/{object_id}/speakers
• GET /v1/objects/{object_id}/diarization
• GET /v1/objects/{object_id}/diarize-status/{task_id}
• GET /v1/voice-profiles
• DELETE /v1/voice-profiles/{profile_id}

Из ответа GET /v1/objects/{object_id}/transcript пропало поле diarized: наполнять его больше нечем. Сама расшифровка не изменилась — она считается при загрузке записи и к диаризации отношения не имела, так что этот маршрут работает как работал.

В SDK удалены парные методы (diarize, get_diarization, rename_speakers, list_voice_profiles и соседние); get_transcript остался.

Где смотреть, что изменилось

Машинная спека лежит по адресу /openapi.json и собирается из живого кода на каждой сборке — не переписывается руками и не отстаёт. Сравнение двух её версий и есть точный список изменений контракта: ключи в ней отсортированы специально, чтобы дифф читался как перечень правок, а не как перестановка строк.

Версия SDK

agentum-cloud-sdk выпускается автоматически при изменениях клиента; номер версии монотонно растёт. Обновление:

pip install -U agentum-cloud-sdk

Покрытие контракта клиентом проверяется тестом на нашей стороне: маршрут без метода в SDK роняет сборку. Практически это значит, что новая возможность API появляется в клиенте в том же релизе, а не «когда-нибудь».