API changes: October 26, 2026

← Changelog · October 2026

FIX-1026-1: API reference field tables reflect update restrictions

Before

API reference field tables presented fields accepted only during creation as writable during record updates as well.

After

The tables preserve createOnly and readonlyOnUpdate flags. Update cards mark these fields as readonly. Their availability during creation is preserved.

Impact on integrators

API behavior and request examples are unchanged. The tables describe existing write restrictions more accurately.

NEW-1026-2: Drive agent documentation links in GET /v1/guide

The diskAgent block of the GET /v1/guide response gained a docs object with eight links to the Drive agent documentation pages: index, capabilities, search, uploadsReserve, uploads, uploadsList, uploadsGet and syncCheck. They lead to the agent overview, the available capabilities, file and folder search, the upload reserve, the content transfer, the list of upload operations, the state of one operation and the object visibility check. The object is returned to a key with the disk scope, the former diskAgent fields stay in place, and the response remains HTTP 200.

BC-1026-3: Org-structure node and mailbox lists reject filtering and sorting

Old format supported until: not provided

Before

GET /v1/humanresources/nodes and GET /v1/mail/mailboxes forwarded filter to Bitrix24 and returned 422 BITRIX_ERROR with a message about an unrecognized filter expression. sort and order returned a successful response even though the record order did not change. The API description declared filter, sort, order, withTotal and the meta.total field for these lists.

After

A filter on any field other than type for nodes is refused before reaching Bitrix24 with 400 UNSUPPORTED_FILTER, and any sort or order with 400 INVALID_SORT_FIELD. The same refusals apply in POST /v1/humanresources/nodes/aggregate and in sub-calls of POST /v1/batch, POST /v1/humanresources/nodes/batch and POST /v1/mail/mailboxes/batch. withTotal is still accepted and has no effect: these lists never report a total count, so withTotal and meta.total are removed from the API description, as are filter for mailboxes and sort and order for both lists.

What integrators should do

Remove filter (except type for nodes), sort and order from these requests. Find nodes by name with POST /v1/humanresources/nodes/search and apply the order you need in your application. Detect the end of the list by meta.hasMore.

BC-1026-4: deploy refuses paths with a `.vibe-prev` directory, which the platform reserves

Old format supported until: not provided

Before

POST /v1/infra/servers/:id/deploy accepted extractTo and dataDirs entries that contain a directory whose name ends in .vibe-prev — for example "dataDirs": ["/opt/app.vibe-prev"] with "extractTo": "/opt/app".

After

A clean deploy keeps the previous version of the application in the <extractTo>.vibe-prev directory and deletes that directory in the clean step and after the flatten step. A data directory at such a path would be erased on every deploy, so an extractTo or a dataDirs entry in which any directory is named <name>.vibe-prev is now refused with 400 PREVIOUS_TREE_DIRECTORY_RESERVED. The check runs before the deploy takes the server, so a refusal changes nothing on the server. The response text names the refused path.

What integrators should do

If extractTo or a dataDirs directory is named that way, move the data to a directory with another name and pass the new path to the deploy. All other paths are accepted as before.

FIX-1026-5: a failed redeploy no longer leaves the application without files

Before

On a clean deploy through POST /v1/infra/servers/:id/deploy, the clean step deleted the contents of extractTo before the new archive was downloaded. If the deploy aborted during the download or right after extraction, the server was left with neither the previous nor the new version of the application. A hang while removing the uploaded archive or while moving a nested folder up into the root of extractTo was not reported as a separate step.

After

The clean step moves the previous tree into the sibling directory <extractTo>.vibe-prev instead of deleting it — except when the move is impossible: extractTo turned out to be a mount point, the file system has no room for a second copy, or the size of the tree could not be measured; the previous contents are then deleted with no way to bring them back. When extractTo is a symbolic link, the step neither moves nor deletes anything: the new archive is extracted over the previous files. If the deploy aborts before the flatten step completes and the outcome of the archive delivery is known, the platform tries to put the moved tree back over the same server connection; a failed move-back is not shown in the deploy response, and the application stays stopped either way. When the download outcome is unknown, the tree is not put back and stays in the sibling directory (see "Impact on integrators"). After flatten the platform deletes the sibling directory; if the deletion does not go through — the server was busy with another command or the connection dropped — the directory stays until the next clean deploy, which deletes it first. data.steps[] gains the remove_uploaded_archive and flatten steps after download: if the command of either one is cut off, error.step names that step. The clean step timeout is 120 seconds.

Impact on integrators

No request changes are needed. During the download the disk holds two copies of the application, the previous one and the new one. If the download outcome is unknown (DOWNLOAD_OUTCOME_UNCONFIRMED, DOWNLOAD_COMMIT_UNCONFIRMED, DOWNLOAD_RELAY_INTERRUPTED, or the connection to the server dropped after the archive delivery started), or the move-back itself or the deletion after flatten failed, the previous tree stays in <extractTo>.vibe-prev and the next deploy deletes it first — copy it out before retrying if you need it. extractTo and dataDirs paths with that name are refused with 400 PREVIOUS_TREE_DIRECTORY_RESERVED.

NEW-1026-6: Five-hour window phase and Cowork turn completion marker

GET /v1/cowork/me and GET /v1/cowork/state return completion.phase (normal, landing, exhausted) and completion.resetAt. A successful POST /v1/chat/completions response may carry X-Cowork-Completion-Mode (landing-finish or reserve) and X-Cowork-Completion-Reset-At when finishing an ongoing turn. A new task is admitted normally before the window runs out.

FIX-1026-7: app address with a name instead of app-… in handlers and appUrl

Before

An address of the form https://<name>.<platform app domain>/…, where <name> is a single label without the app- prefix, was accepted in appUrl, in a placement handler, in the HANDLER of a business process robot or activity, and in a bot webhookUrl just like an app-… address, and was stored as is, but it led nowhere: before app names existed, such an address was bound to no app, and a request to it got a platform answer that the app was not found. No placement, robot or bot with such an address worked. A name is not bound to an app forever, so an address stored with it could later lead to another app.

After

If the name is bound to a server of your Bitrix24 account, the address is stored as the app-… address of that server with the same path and parameters. Any other name is refused with 422 APP_HOST_NOT_ALLOWED_HERE before Bitrix24 is called, and nothing is stored. Inside POST /v1/batch the same code arrives in the error of the single call.

Affected endpoints: POST /v1/apps, PATCH /v1/apps/:id, POST /v1/apps/:id/publish, POST /v1/placements/bind, POST /v1/bots, PATCH /v1/bots/:botId, POST /v1/bizproc-robots, POST /v1/bizproc-activities, POST /v1/batch, POST /v1/cowork/portal-rest

Impact on integrators

No change is needed, so this entry is classified as a fix, not as a breaking change. The refusal applies only to an address that led to no app before this change, so no working integration could rely on it. App names appear only with this change and are enabled for Bitrix24 accounts gradually. The refusal applies only to an address with a name; app-… addresses and addresses outside the platform are checked as before. In handlers and appUrl, use the app's app-… address.

NEW-1026-8: MCP package 3.3.0: sign-in flow and CRM form guidance

In @bitrix24/mcp-vibecode-api 3.3.0, the add-user-login flow asks which sign-in providers to offer and supports a chosen provider that needs no registration: ready-made environment variable values are applied without requesting a client id.

Compared with 3.2.1, call_api guidance for CRM forms covers reading configuration and dictionaries, creating, updating, deleting, activating and validating forms without saving, submitting results and sending a form to an open-line session, embedding settings and connected places. Writes require a READWRITE key; validation without saving also works with READONLY.

The entity reference no longer suggests sort for lists without sorting support, including departments, structure nodes and mailboxes. Server creation guidance names Node.js 24 as the default runtime. Deploy and diagnostic instructions require waiting for a server resize on EXEC_BUSY, and the deploy flow explains when the previous application tree is preserved and restored. Upgrade the package and restart the MCP session to load the new guidance.

FIX-1026-10: Company connection daily caps are now optional

Before

A missing daily cap for the Bitrix24 account or company connection blocked connection and requests.

After

Daily caps are independent and optional: null means no corresponding cap. General limits, usage accounting and billing remain in force. CONNECT_COMPANY_NOT_READY reports temporary technical conditions for connection, not a requirement to set a daily cap. Company key issuance remains closed until the technical conditions are met.

NEW-1026-11: List unread mention and reaction marks

GET /v1/chats/anchors returns all your anchors across chats in one request, ordered by messageId, highest first. There are no query parameters. The im scope is required, and read-only keys are supported. Reading does not remove marks or join chats.

The method is rolling out in the im 26.1600.0 update. Until the update reaches your Bitrix24 account, the call returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

BC-1026-12: Access for hour-long cloud tasks

Old format supported until: not provided

Before

Key and consent lifetime checks for a one-time cloud task covered a short run.

After

Creating or rescheduling a one-time task through POST /v1/cowork/cloud-tasks and PATCH /v1/cowork/cloud-tasks/{id} requires access until the scheduled time plus 71 minutes: 70 minutes for the run including preparation and completion, and one minute of allowed start lateness. Insufficient key lifetime returns CREDENTIAL_EXPIRING. Key and consent lifetimes are never extended automatically.

What integrators should do

Before confirming a task, check that the current access covers the complete run. If it is refused, renew access and confirm the task again.

FIX-1026-13: Incomplete aggregate counts are now marked

Before

When Bitrix24 omitted total, the platform recovered the count by paging. A page error or the 5000-row ceiling could stop the walk, but POST /v1/deals/aggregate and other POST aggregates returned 200 with meta.truncated: false and presented the partial count as exact.

After

The response remains 200. When count recovery stops early, data.truncated and meta.truncated are true, while count and meta.totalRecords are lower bounds. meta.warnings contains AGGREGATE_TRUNCATED. A failed or malformed page has a safe meta.pageErrorSample with code AGGREGATE_COUNT_PAGE_FAILED; the ceiling is marked by meta.countWalkLimit: 5000. A complete count still has meta.truncated: false.

Impact on integrations

Check meta.truncated before treating count as an exact total. If it is true, narrow the filter or retry the request.

BC-1026-14: Web search uses AI quota

Old format supported until: not provided

Before

Paid POST /v1/search and POST /v1/research requests with sufficient wallet balance succeeded and deducted Ꝟ from the wallet.

After

Requests first use the Bitrix24 account AI quota, while requests with a Cowork key use the seat quota. Usage beyond the AI quota uses the wallet when overage is enabled and available. Sufficient wallet balance no longer always guarantees that a request can proceed. Before the SSE stream starts, the following ordinary HTTP error responses may occur:

• 402 AI_QUOTA_EXHAUSTED — AI quota is exhausted and wallet overage is unavailable. Fields error.reason and error.resetAt describe the reason and reset time.
• 429 AI_PACING_LIMITED — the quota pacing limit is reached. The response includes error.reason, error.overageDenied, error.resetAt and the Retry-After header in seconds.
• 402 COWORK_QUOTA_EXHAUSTED — a Cowork seat quota window is exhausted. Field error.window is fiveHour, week or month. The response includes error.resetAt and the Retry-After header in seconds.
• 402 COWORK_SUBSCRIPTION_INACTIVE — there is no active Cowork seat.

The synchronous search response and the done event in both SSE streams gain a billing_source field: wallet, quota, cowork or byok. The value wallet includes usage beyond the AI quota. The field is omitted for a free request using a platform key. Field cost_vibes means the amount deducted from the wallet: it is 0 when using AI quota, Cowork seat quota or your own key.

The byModel array in GET /v1/ai/quota may include a row with the reserved modelId: "web-search": this is the quota share used by web search, rather than a model in the catalogue. Fields calls and pctOfLimit show the request count and share of the monthly limit.

What integrators should do

Handle the new refusals before opening SSE. For quota limits, wait until error.resetAt or for the delay in Retry-After. To pay for usage beyond the AI quota, enable overage in the account dashboard and top up the wallet. If a Cowork seat is inactive, activate or resume it. You can also switch search to your own key (BYOK). Read the payment source from billing_source and the wallet deduction from cost_vibes. In the quota breakdown, handle web-search separately from catalogue models.

NEW-1026-15: Rejection before a personal model call starts

Personal Cowork calls through /v1/ai/chat/completions, /v1/ai/images/generations and /v1/ai/audio/transcriptions may return HTTP 503 with USAGE_BASIS_UNAVAILABLE in error.type when call registration is temporarily unavailable. The provider request has not started in this case; the client can retry later.

FIX-1026-16: temporary promotion limit-reset failures can be retried safely

Before

Under contention, POST /v1/cowork/limits/reset waited for a lock and returned a generic 500 error if it failed.

After

A V1 call without resetVersion returns 503 COWORK_LIMIT_RESET_BUSY only for temporary contention. Other failures return a generic 500 error. In both cases, the right and usage windows remain unchanged, and no reset is deferred. Successful responses still contain rightId, usedAt and alreadyUsed; repeating a spent right returns alreadyUsed: true and the original spend time.

Impact on integrators

After COWORK_LIMIT_RESET_BUSY, retry the same rightId after a pause. This is a new attempt; no request UUID or operation polling is needed.

NEW-1026-17: An overly complex request body is refused with 413 BODY_TOO_COMPLEX

A request body with more than 100,000 JSON values, an array longer than 20,000 items or nesting deeper than 128 levels is refused with 413 BODY_TOO_COMPLEX before the method runs. The body root, every array item and every object field each count as one value. A string of any length, a base64 file included, is one value. The error.message names the limit that was hit.

On AI methods (/v1/ai/*, /v1/chat/*, /v1/audio/*, /v1/models) the refusal comes in the OpenAI-compatible envelope: error.code is body_too_complex and error.type is invalid_request_error.

The limits sit well above the largest bodies that API methods accept. Retrying the same body will not help: split the data across several requests. See error codes.

NEW-1026-18: company key for verified self-hosted Bitrix24 accounts

The company key in Partner Connect is also available on self-hosted Bitrix24 accounts verified by the platform. Application permissions and administrator consent are still required.