# Изменения API: 26 октября 2026

[← Журнал изменений](/docs/changelog) · [Октябрь 2026](/docs/changelog/2026-10)

### FIX-1026-1: Справочник API учитывает ограничения полей при обновлении

**Было**

Таблицы полей в справочнике API показывали поля, доступные только при создании,
как доступные и при обновлении записи.

**Стало**

Таблицы сохраняют признаки `createOnly` и `readonlyOnUpdate`. В карточках
обновления такие поля отмечены `readonly`. При создании их доступность сохраняется.

**Влияние на интеграторов**

Поведение API и примеры запросов не изменились. Таблицы точнее описывают
существующие ограничения записи.

### NEW-1026-2: Ссылки на документацию агента Диска в GET /v1/guide

Блок `diskAgent` в ответе `GET /v1/guide` получил объект `docs` с восемью ссылками на страницы документации агента Диска: `index`, `capabilities`, `search`, `uploadsReserve`, `uploads`, `uploadsList`, `uploadsGet` и `syncCheck`. Они ведут на обзор агента, описание доступных возможностей, поиск файлов и папок, резерв загрузки, передачу содержимого, список операций загрузки, состояние одной операции и проверку видимости объектов. Объект приходит ключу со скоупом `disk`, прежние поля `diskAgent` остались на месте, ответ по-прежнему HTTP 200.

### BC-1026-3: Списки узлов оргструктуры и почтовых ящиков отклоняют фильтр и сортировку

> Поддержка старого формата до: не предусмотрена

**Было**

[GET /v1/humanresources/nodes](/docs/humanresources/nodes/list) и [GET /v1/mail/mailboxes](/docs/mail/mailboxes/list) пропускали `filter` в Битрикс24 и возвращали `422 BITRIX_ERROR` с сообщением о нераспознанном выражении фильтра. `sort` и `order` возвращали успешный ответ, хотя порядок записей не менялся. Описание API объявляло у этих списков параметры `filter`, `sort`, `order`, `withTotal` и поле `meta.total`.

**Стало**

Фильтр по любому полю, кроме `type` у узлов, отклоняется до обращения к Битрикс24 кодом `400 UNSUPPORTED_FILTER`, любой `sort` или `order` — кодом `400 INVALID_SORT_FIELD`. Те же отказы действуют в [POST /v1/humanresources/nodes/aggregate](/docs/humanresources/nodes/aggregate) и в подвызовах [POST /v1/batch](/docs/batch), `POST /v1/humanresources/nodes/batch` и `POST /v1/mail/mailboxes/batch`. `withTotal` по-прежнему принимается и ни на что не влияет: общее количество у этих списков не приходит, поэтому `withTotal` и `meta.total` убраны из описания API, а `filter` у ящиков и `sort`, `order` у обоих списков из него исключены.

**Что делать интеграторам**

Уберите `filter`, кроме `type` у узлов, а также `sort` и `order` из этих запросов. Узлы ищите по названию через [POST /v1/humanresources/nodes/search](/docs/humanresources/nodes/search), нужный порядок задавайте в своём приложении. Конец выдачи определяйте по `meta.hasMore`.

### BC-1026-4: деплой отвергает пути с каталогом `.vibe-prev`, который занят платформой

> Поддержка старого формата до: не предусмотрена

**Было**

[POST /v1/infra/servers/:id/deploy](/docs/infra/deploy/deploy) принимал `extractTo` и элементы `dataDirs`, в которых есть каталог с именем, оканчивающимся на `.vibe-prev`, — например `"dataDirs": ["/opt/app.vibe-prev"]` при `"extractTo": "/opt/app"`.

**Стало**

Чистый деплой хранит прежнюю версию приложения в каталоге `<extractTo>.vibe-prev` и удаляет этот каталог на шаге `clean` и после шага `flatten`. Каталог данных с таким путём стирался бы на каждом деплое, поэтому `extractTo` или элемент `dataDirs`, в котором любой каталог называется `<имя>.vibe-prev`, теперь отвергается ответом `400 PREVIOUS_TREE_DIRECTORY_RESERVED`. Проверка идёт до того, как деплой займёт сервер, поэтому отказ ничего на сервере не меняет. Текст ответа называет отвергнутый путь.

**Что делать интеграторам**

Если `extractTo` или каталог из `dataDirs` назван так, перенесите данные в каталог с другим именем и передайте в деплой новый путь. Остальные пути принимаются как раньше.

### FIX-1026-5: неудачный повторный деплой больше не оставляет приложение без файлов

**Было**

При чистом деплое через [POST /v1/infra/servers/:id/deploy](/docs/infra/deploy/deploy) шаг `clean` стирал содержимое `extractTo` до скачивания нового архива. Если деплой обрывался на скачивании или сразу после распаковки, на сервере не оставалось ни прежней, ни новой версии приложения. Зависание при удалении загруженного архива или при подъёме вложенной папки в корень `extractTo` не называлось отдельным шагом.

**Стало**

Шаг `clean` переносит прежнее дерево в соседний каталог `<extractTo>.vibe-prev` вместо стирания — кроме случаев, когда перенос невозможен: `extractTo` оказался точкой монтирования, на файловой системе нет места на вторую копию либо размер дерева не удалось измерить; тогда прежнее содержимое стирается без возможности вернуть его. Если `extractTo` — символическая ссылка, шаг ничего не переносит и не стирает: новый архив распаковывается поверх прежних файлов. Если деплой обрывается до завершения шага `flatten` и исход доставки архива известен, платформа пытается вернуть перенесённое дерево на место по той же связи с сервером; неудача возврата в ответе деплоя не видна, а приложение в любом случае остаётся остановленным. При неизвестном исходе скачивания дерево на место не возвращается и остаётся в соседнем каталоге (см. «Влияние на интеграторов»). После `flatten` платформа удаляет соседний каталог; если удаление не прошло — сервер был занят другой командой или оборвалась связь, — каталог остаётся до следующего чистого деплоя, который удаляет его первым. В `data.steps[]` после `download` появились шаги `remove_uploaded_archive` и `flatten`: если команда одного из них оборвалась, `error.step` называет этот шаг. Таймаут шага `clean` — 120 секунд.

**Влияние на интеграторов**

Запросы менять не требуется. На время скачивания на диске лежат две копии приложения — прежняя и новая. Если исход скачивания неизвестен (`DOWNLOAD_OUTCOME_UNCONFIRMED`, `DOWNLOAD_COMMIT_UNCONFIRMED`, `DOWNLOAD_RELAY_INTERRUPTED` или обрыв связи с сервером после начала доставки архива) либо не удался сам возврат или удаление после `flatten`, прежнее дерево остаётся в `<extractTo>.vibe-prev`, и следующий деплой удаляет его первым — заберите его до повтора, если оно нужно. Пути `extractTo` и `dataDirs` с таким именем отвергаются кодом `400 PREVIOUS_TREE_DIRECTORY_RESERVED`.

### NEW-1026-6: Фаза пятичасового окна и признак завершения хода Коворк/Код

[GET /v1/cowork/me](/docs/cowork/me) и [GET /v1/cowork/state](/docs/cowork/state) возвращают `completion.phase` (`normal`, `landing`, `exhausted`) и `completion.resetAt`. Успешный ответ [POST /v1/chat/completions](/docs/ai/chat/completions) при завершении начатого хода может нести заголовки `X-Cowork-Completion-Mode` (`landing-finish` или `reserve`) и `X-Cowork-Completion-Reset-At`. Новая задача перед исчерпанием окна принимается обычно.

### FIX-1026-7: адрес приложения с именем вместо app-… в обработчиках и appUrl

**Было**

Адрес вида `https://<имя>.<домен приложений платформы>/…`, где `<имя>` — одна метка без префикса `app-`, принимался в `appUrl`, в обработчике места встройки, в `HANDLER` робота и действия бизнес-процесса и в `webhookUrl` бота так же, как адрес `app-…`, и сохранялся как есть, но никуда не вёл: до появления имён приложений такой адрес не был закреплён ни за одним приложением, и запрос по нему получал от платформы ответ, что приложение не найдено. Ни встройка, ни робот, ни бот с таким адресом не работали. Имя не закреплено за приложением навсегда, поэтому сохранённый с ним адрес мог бы со временем вести на чужое приложение.

**Стало**

Если имя закреплено за сервером вашего аккаунта Битрикс24, адрес сохраняется как адрес `app-…` этого сервера с тем же путём и параметрами. Любое другое имя отклоняется ответом `422 APP_HOST_NOT_ALLOWED_HERE` до обращения к Битрикс24, и ничего не сохраняется. Внутри [POST /v1/batch](/docs/batch) тот же код приходит в ошибке отдельного вызова.

**Затронутые эндпоинты:** [POST /v1/apps](/docs/apps/create), [PATCH /v1/apps/:id](/docs/apps/update), [POST /v1/apps/:id/publish](/docs/apps/publish), [POST /v1/placements/bind](/docs/apps/placements/bind), [POST /v1/bots](/docs/bots/management/create), [PATCH /v1/bots/:botId](/docs/bots/management/update), [POST /v1/bizproc-robots](/docs/entities/bizproc-robots), [POST /v1/bizproc-activities](/docs/entities/bizproc-activities), [POST /v1/batch](/docs/batch), `POST /v1/cowork/portal-rest`

**Влияние на интеграторов**

Менять ничего не нужно, поэтому запись отнесена к исправлениям, а не к несовместимым изменениям. Отказ получает только адрес, который до этого изменения ни к какому приложению не вёл, так что ни одна работавшая интеграция на него опираться не могла. Имена приложений появляются только вместе с этим изменением и включаются для аккаунтов Битрикс24 постепенно. Отказ приходит только на адрес с именем; адреса `app-…` и адреса вне платформы проверяются как раньше. В обработчиках и `appUrl` указывайте адрес `app-…` приложения.

### NEW-1026-8: MCP-пакет 3.3.0: сценарий входа и подсказки CRM-форм

В `@bitrix24/mcp-vibecode-api` 3.3.0 сценарий `add-user-login` предлагает выбрать провайдеров входа и поддерживает выбранного провайдера без регистрации: готовые значения переменных окружения применяются без запроса client id.

По сравнению с 3.2.1 подсказки `call_api` для CRM-форм описывают чтение конфигурации и справочников, создание, изменение, удаление, активацию и проверку форм без сохранения, отправку результатов и формы в открытую линию, настройки встраивания и связанные места размещения. Для записи требуется ключ READWRITE; проверка без сохранения доступна и с READONLY.

Справочник сущностей больше не предлагает `sort` для списков без поддержки сортировки, включая подразделения, узлы структуры и почтовые ящики. При создании сервера подсказки предлагают Node.js 24 по умолчанию. Инструкции deploy и диагностики требуют дождаться изменения размера сервера при `EXEC_BUSY`, а сценарий deploy поясняет условия сохранения и возврата прежнего дерева приложения. Обновите пакет и перезапустите MCP-сессию, чтобы загрузить новые подсказки.

### FIX-1026-9: Сбой входа в приложение больше не считается ошибкой клиента

**Было**

При сбое чтения данных пользователя `POST /v1/app-user-signin/bitrix24/token` отвечал `400 INVALID_CODE`. SDK учитывал такой отказ как ошибку клиента и после нескольких отказов блокировал его вход.

**Стало**

В этом случае метод отвечает `503 TEMPORARILY_UNAVAILABLE`. SDK не учитывает этот ответ в счётчике ошибок клиента.

**Влияние на интеграторов**

Обновлять SDK не требуется. Начните вход заново: одноразовый код уже использован, его повторный обмен возвращает `400 CODE_ALREADY_USED`.

### FIX-1026-10: Дневные потолки подключения компании стали необязательными

**Было**

Отсутствие дневного потолка портала или подключения компании считалось препятствием для подключения и выполнения запросов.

**Стало**

Дневные потолки независимы и необязательны: `null` означает отсутствие соответствующего потолка. Общие ограничения, учёт расхода и тарификация сохраняются. `CONNECT_COMPANY_NOT_READY` сообщает о временных технических условиях подключения, а не об обязательности дневного потолка. Выдача ключей компании остаётся закрытой до выполнения технических условий.

### NEW-1026-11: Перечень непрочитанных упоминаний и реакций

[GET /v1/chats/anchors](/docs/chats/messages/anchors-list) отдаёт все ваши якоря во всех чатах одним запросом, по `messageId` от большего к меньшему. Параметров запроса нет. Нужен скоуп `im`, ключ только для чтения подходит. Чтение не снимает отметки и не вступает в чаты.

Метод в процессе раскатки — выходит в обновлении `im 26.1600.0`. До обновления портала вызов возвращает `422 METHOD_NOT_YET_AVAILABLE` с `error.release`.

### BC-1026-12: Доступ для часовых облачных заданий

> Поддержка старого формата до: не предусмотрена

**Было**

Проверка срока ключа и согласия для разового облачного задания учитывала короткий запуск.

**Стало**

Создание и перенос разового задания через `POST /v1/cowork/cloud-tasks` и `PATCH /v1/cowork/cloud-tasks/{id}` требуют доступа до времени запуска плюс 71 минута: 70 минут на запуск с учётом подготовки и завершения и одна минута допустимого опоздания. Недостаточный срок ключа вызывает `CREDENTIAL_EXPIRING`. Срок ключа и согласия автоматически не продлевается.

**Что делать интеграторам**

Перед подтверждением задания проверьте, что срок действующего доступа покрывает весь запуск. При отказе обновите доступ и повторно подтвердите задание.

### FIX-1026-13: Неполный счёт в агрегации теперь помечен

**Было**

Если Битрикс24 не возвращал `total`, платформа восстанавливала число по страницам. Ошибка страницы или достижение предела 5000 строк могли оборвать обход, но [POST /v1/deals/aggregate](/docs/entities/deals/aggregate) и другие POST-агрегации отвечали `200` с `meta.truncated: false` и частичным `count` как с точным числом.

**Стало**

Ответ остаётся `200`. При обрыве восстановительного счёта `data.truncated` и `meta.truncated` равны `true`, а `count` и `meta.totalRecords` обозначают нижнюю границу. `meta.warnings` содержит `AGGREGATE_TRUNCATED`. Ошибка или неверная страница отмечена безопасным `meta.pageErrorSample` с кодом `AGGREGATE_COUNT_PAGE_FAILED`; достижение предела — `meta.countWalkLimit: 5000`. Полный счёт по-прежнему отвечает с `meta.truncated: false`.

**Влияние на интеграторов**

Проверяйте `meta.truncated` перед использованием `count` как точного итога. При `true` сузьте фильтр или повторите запрос.

### BC-1026-14: Веб-поиск расходует квоту ИИ

> Поддержка старого формата до: не предусмотрена

**Было**

Платные запросы [POST /v1/search](/docs/search/run) и [POST /v1/research](/docs/search/research) при достаточном балансе кошелька выполнялись со списанием Ꝟ с кошелька.

**Стало**

Запросы сначала расходуют квоту ИИ портала, а запросы с ключом Коворк/Код — квоту места. Сверх квоты ИИ используется кошелёк, если перерасход разрешён и доступен. Достаточного баланса кошелька больше не всегда достаточно для выполнения запроса. До начала потока SSE возможны обычные HTTP-ответы с ошибкой:

- `402 AI_QUOTA_EXHAUSTED` — квота ИИ исчерпана, оплата сверх квоты недоступна. Поля `error.reason` и `error.resetAt` описывают причину и время сброса.
- `429 AI_PACING_LIMITED` — достигнут лимит равномерного расходования квоты. Ответ содержит `error.reason`, `error.overageDenied`, `error.resetAt` и заголовок `Retry-After` в секундах.
- `402 COWORK_QUOTA_EXHAUSTED` — исчерпано окно квоты места Коворк/Код. Поле `error.window` принимает `fiveHour`, `week` или `month`. Ответ содержит `error.resetAt` и заголовок `Retry-After` в секундах.
- `402 COWORK_SUBSCRIPTION_INACTIVE` — нет активного места Коворк/Код.

В синхронном ответе поиска и событии `done` обоих потоков SSE появляется поле `billing_source`: `wallet`, `quota`, `cowork` или `byok`. Значение `wallet` включает оплату сверх квоты ИИ. Для бесплатного запроса с платформенным ключом поле отсутствует. Поле `cost_vibes` означает сумму, списанную с кошелька: при оплате квотой ИИ, квотой места Коворк/Код или своим ключом оно равно `0`.

В `byModel` ответа [GET /v1/ai/quota](/docs/ai/consumption/quota) может появиться строка с зарезервированным `modelId: "web-search"`: это доля квоты на веб-поиск, а не модель каталога. Поля `calls` и `pctOfLimit` показывают число запросов и долю месячного лимита.

**Что делать интеграторам**

Обрабатывайте новые отказы до открытия SSE. При ограничении квоты дождитесь `error.resetAt` или задержки из `Retry-After`. Для оплаты сверх квоты ИИ разрешите перерасход в кабинете и пополните кошелёк. При неактивном месте Коворк/Код активируйте или возобновите его. Для поиска можно также перейти на свой ключ (BYOK). Источник оплаты определяйте по `billing_source`, а сумму списания с кошелька — по `cost_vibes`. В разбивке квоты учитывайте `web-search` отдельно от моделей каталога.

### NEW-1026-15: Отказ до начала личного вызова модели

Личные вызовы Коворк/Код через `/v1/ai/chat/completions`, `/v1/ai/images/generations` и `/v1/ai/audio/transcriptions` могут вернуть HTTP 503 с кодом `USAGE_BASIS_UNAVAILABLE` в `error.type`, если временно недоступна регистрация вызова. В этом случае запрос провайдеру ещё не отправлен; клиент может повторить запрос позже.

### FIX-1026-16: временную ошибку сброса лимитов по акции можно безопасно повторить

**Было**

При занятости `POST /v1/cowork/limits/reset` ждал блокировку и при неудаче отвечал общей ошибкой 500.

**Стало**

Вызов V1 без `resetVersion` возвращает `503 COWORK_LIMIT_RESET_BUSY` только при временной занятости. Прочие сбои возвращают общую ошибку 500. В обоих случаях право и окна расхода остаются целыми, отложенного сброса нет. Успешный ответ по-прежнему содержит `rightId`, `usedAt` и `alreadyUsed`, повтор потраченного права возвращает `alreadyUsed: true` и время первой траты.

**Влияние на интеграторов**

После `COWORK_LIMIT_RESET_BUSY` повторите тот же `rightId` с паузой. Это новая попытка, UUID запроса и опрос операции не нужны.

### NEW-1026-17: Слишком сложное тело запроса отклоняется ответом 413 BODY_TOO_COMPLEX

Тело запроса, в котором больше 100 000 значений JSON, есть массив длиннее 20 000 элементов или вложенность глубже 128 уровней, отклоняется ответом `413 BODY_TOO_COMPLEX` до выполнения метода. Значениями считаются сам корень тела, каждый элемент массива и каждое поле объекта. Строка любой длины, в том числе файл в base64, — одно значение. Сообщение в `error.message` называет сработавший предел.

На методах AI (`/v1/ai/*`, `/v1/chat/*`, `/v1/audio/*`, `/v1/models`) отказ приходит в конверте, совместимом с OpenAI: `error.code` равен `body_too_complex`, `error.type` — `invalid_request_error`.

Пределы выбраны с запасом над самыми крупными телами, которые принимают методы API. Повтор того же тела не поможет: разбейте данные на несколько запросов. Подробнее — [коды ошибок](/docs/errors).

### NEW-1026-18: ключ компании для проверенных коробочных порталов

Ключ компании в Partner Connect также доступен на коробочных порталах Битрикс24, проверенных платформой. Требования к разрешениям приложения и согласию администратора сохраняются.
