API changes: October 30, 2026

← Changelog · October 2026

NEW-1030-1: a distinct refusal when the key does not manage the server

POST /v1/infra/servers/{id}/start and POST /v1/infra/servers/{id}/refresh return 403 WRONG_KEY when a live server in the Bitrix24 account is proven to be related to the key owner or one of its live applications, but is managed by another key. The response advises rebinding the server through a human session. Unrelated, deleted and unknown servers still return 404 SERVER_NOT_FOUND.

FIX-1030-2: Paginated listing of storage root children

Before

POST /v1/storages/{id}/children returned only the first portion of root objects with no continuation signal. A root with many files and folders appeared to be a complete list.

After

A valid response remains HTTP 200: the request body accepts limit from 1 to 500 and offset, and the response includes meta.total, meta.hasMore, and meta.nextOffset. Repeat the same filter to read the remaining objects. If Bitrix24 returns an incomplete or unverifiable portion, the operation returns 502 DISK_READ_UNAVAILABLE instead of a misleading complete list.

Impact on integrators

Read pages until meta.hasMore is false, passing meta.nextOffset and the same filter. Treat 502 DISK_READ_UNAVAILABLE as a read failure and retry later.

FIX-1030-3: descending id sort for Disk files and folders

Before

GET /v1/files and GET /v1/folders returned rows in ascending id order for a descending id sort — ?sort=-id or ?order[id]=desc. There was no error and no meta.warnings, so a "newest files first" query silently came back in the opposite order: ascending id worked, descending was ignored.

After

A descending id sort works: the same requests return rows from the highest id to the lowest, matching the other API entities. Sorting by other fields (name, createdAt) and an ascending id sort are unchanged.

Impact on integrators

No code changes are needed. If a "newest first" listing was built on ?sort=-id, the order is now the expected one.

FIX-1030-4: a solution event reaches a Bitrix24 account with the updated module

Before

POST /v1/solution-events answered 409 PORTAL_NOT_SUPPORTED to every event, even when the module on the Bitrix24 account was already updated.

After

The event is passed to a Bitrix24 account with module 26.1100.0 or later. An older module still gives 409 PORTAL_NOT_SUPPORTED, and the message names the required version. A Bitrix24 account refusal because the solution is unavailable to the card owner comes as documented: 409 SOLUTION_NOT_ELIGIBLE, not 503 PORTAL_UNAVAILABLE.

Impact on integrators

No request changes are needed. The Bitrix24 account did not accept the events that got 409 PORTAL_NOT_SUPPORTED: they can be sent again.

NEW-1030-5: Chats: open the discussion of a post in one call

POST /v1/chats/messages/:messageId/comments/chat opens the comment chat of a channel post and returns the same object as GET /v1/chats/:dialogId/load: the chat, the first page of messages, pinned messages, users and files. It takes the same messageLimit, pinLimit and ignoreMark parameters; other parameters and a request body are refused with 400 INVALID_PARAMS. When the post has no comment chat yet, Bitrix24 creates it and the caller becomes a member, so a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any Bitrix24 call. The call is not retried automatically. The Bitrix24 refusal code arrives in error.b24Code.

BC-1030-6: OAuth bot registration and events

Old format supported until: not provided

Before

A new OAuth bot could register successfully, but subsequent calls with the same application key returned BOT_OWNERSHIP_ERROR. Registering a webhook targeting the platform receiver could return 201 without fresh verification of the application installation.

After

POST /v1/bots registers a new OAuth bot without sending botToken and verifies ownership through the same application and exact id/code before completing registration. Both fetch and webhook are supported. The platform receiver requires a fresh verified application INSTALL/placement; otherwise the request returns 409 BOT_APP_EVENT_ENROLLMENT_REQUIRED. A historical application token alone does not verify installation. Changing a new OAuth bot's botToken returns 409 BOT_OAUTH_POLICY_INVALID. Bots registered under the previous contract keep their existing behavior and are not automatically transferred or recreated. The ownership and event admission rules also apply to PATCH /v1/bots/:botId.

Opening an installed application with a valid application token and a verified Bitrix24 account user remains available when optional callback enrollment is throttled, its verification is unavailable, the author is blocked or soft-deleted, or the owner membership/paired key is ineligible. Callback enrollment is neither created nor updated in these cases. Once irreversible author erasure starts, the application still returns 403 APP_UNAVAILABLE without issuing tokens. A token positively identified as belonging to another OAuth application is still refused.

Restoring eligibility allows fresh verification on the next open. Mandatory account user verification and application ownership verification during token recovery remain in place.

For an app-owned OAuth bot, ownership transfer to a personal/webhook key or a key of another OAuth application (client_id) returns 400 TARGET_KEY_INVALID with error.reason=application_mismatch; ownership stays unchanged. A key of the same application must still pass the other target-key eligibility checks.

What integrators should do

If the application's callback binding changes during an operation that requires event admission, the request returns 409 BOT_APP_EVENT_CREDENTIAL_CHANGED without Retry-After. Obtain fresh verified INSTALL/placement confirmation for the bound application, then retry the request. This refusal can occur during registration, bot updates and resubscription; it does not replace the rule that held events are discarded when an already-proved identity is published.

Resubscription through POST /v1/bots/:botId/resubscribe also returns the OAuth 409 refusals described in OpenAPI; these refusals do not carry Retry-After.

INSTALL again accepts a top-level DOMAIN when auth.domain is absent or empty. Both nonempty values must agree with each other and the stored account; conflicts or invalid types return 403 before external calls. INSTALL without auth.client_id is acknowledged and ignored without external calls or token changes; that response does not verify installation. Independent member_id and OAuth application verification remain mandatory for callback enrollment. Saving identical OAuth credentials through relink preserves verified callback enrollment; changing client_id or secret requires fresh verification. Different applications belonging to the same author can now open concurrently during optional callback verification.

The platform receiver also requires verified Agent or ManagedBot ownership. An application bot without that owner receives 409 BOT_APP_EVENT_CONSUMER_REQUIRED before any Bitrix24 write. Publication of the verified bot identity and lifecycle continues when the basis for event delivery is lost; held events are discarded. After a Bitrix24 account address change, held events may be delivered after verified identity recovery only if the callback binding is unchanged. If the binding changes or is absent, those events are permanently discarded while identity recovery continues. This does not guarantee delivery of every event.

Before registering a new webhook targeting the platform receiver, complete an application INSTALL/placement verified by the platform, then retry through an Agent or ManagedBot. An OAuth bot without that owner or a bound application installation can use fetch or its own receiver. Use a key of the same application without botToken to work with a new OAuth bot.

FIX-1030-7: a bot operation no longer promises a retry that changes nothing

Before

When an operation on an existing bot stopped on a refusal of the stored rights by the Bitrix24 account — the key no longer reads the bot, the old token is rejected, the open-line settings cannot be read — POST /v1/bots and POST /v1/bots/registrations/:code/recover answered 409 BOT_EFFECT_IN_PROGRESS with a Retry-After header. A repeat after that delay received the same answer again, with no limit.

After

That refusal now comes as 409 BOT_UNAVAILABLE without the Retry-After header. A refusal caused by a connection failure, a limit or a timeout still comes as 409 BOT_EFFECT_IN_PROGRESS with Retry-After: that branch is unchanged.

Impact on integrators

Treat BOT_UNAVAILABLE as requiring an action: do not repeat the request on a timer, check that the key still has access to the Bitrix24 account and that the bot is not deleted. A BOT_EFFECT_IN_PROGRESS answer with a Retry-After header is handled as before.

FIX-1030-8: numeric ID arrays in response descriptions

Before

OpenAPI described the elements of User.departmentId, Deal.contactIds and Quote.contactIds as strings, although responses contain numbers. Validating a response against that schema rejected populated numeric arrays.

After

The response schema describes these elements as numbers, including at /v1/users/me. The /v1/users/fields, /v1/deals/fields, /v1/quotes/fields endpoints and fieldsDetailed in /v1/guide publish a separate readItemSchema: { "type": "number" } description. Input schemas, accepted values, response data and element order are preserved; Deal.contactIds remains read-only.

FIX-1030-9: The daily free API allowance is shared across an owner's keys

Before

When excess usage was chargeable, the free allowance could be applied again in different hours and to different keys belonging to the same owner in one company. For example, two groups of 600 requests could remain entirely free under a daily allowance of 1000 requests.

After

All keys belonging to an owner in one company consume one daily allowance, including requests that were previously free. In this example, 200 requests above the allowance are charged. Revoking an existing key does not restore consumed allowance, and a price change does not change the number of requests already counted. Previously recorded charges are not recalculated.

FIX-1030-10: previous webhook cleanup no longer closes Bitrix24 for a Company connection

Before

After a Company connection changed holders, GET /v1/connect/company/status returned bitrix_ready: false and reason_code: CONNECTION_WEBHOOK_CLEANUP_PENDING until the platform deleted the previous holder's webhook in Bitrix24. Bitrix24 calls with the connection key were rejected with the same code during that time.

After

Bitrix24 is available as soon as the connection has a working webhook of the current holder: bitrix_ready does not depend on cleanup of previous webhooks. webhook_cleanup reports pending while cleanup continues, including when a previous webhook cannot be deleted, and attention_required when the outcome of creating a webhook is unknown. The CONNECTION_WEBHOOK_CLEANUP_PENDING code remains for a connection with no working webhook whose webhook creation outcome is unknown.

Impact on integrators

No changes are required. bitrix_ready still reports Bitrix24 availability.