API changes: August 29, 2026

← Changelog · August 2026

FIX-0829-1: importable field flag in guide

Before

In GET /v1/guide, the detailed data.entities[].fieldsDetailed contract did not indicate whether a field could be set during import.

After

For such fields, data.entities[].fieldsDetailed now includes importable: true. The response remains HTTP 200, and the compact data.entities[].fields map is unchanged.

NEW-0829-2: a link to a public app expands into a card

A link to an app in PUBLIC mode reached a messenger or Bitrix24 chat as a bare subdomain address. The preview fetcher got the same page a browser did, and there was nothing for it to show.

A link to an app in PUBLIC mode expands into a card with a title, a description and an image. The data comes from the app's catalogue entry; with no catalogue title the server name is used, with no icon the platform image. The gateway assembles the card itself: the app receives no request, and a sleeping server is not woken. Under any other access policy there is no card — the preview fetcher gets a neutral page with no title, description or image. A card that has already been shown cannot be recalled: the receiving side caches it, so switching the policy to a private one closes off new requests only. More — Authorization in a Black Hole app.

BC-0829-3: lead filters now support stage semantics

Old format supported until: not provided

Before

GET /v1/leads, POST /v1/leads/search, and POST /v1/leads/aggregate with a stageSemanticId filter returned UNKNOWN_FILTER_FIELD. A stageSemanticId field sent in create, update, import, entity batch, or global batch was ignored.

After

The filter accepts P (in progress), S (success), and F (failure). Sorting by stageSemanticId is also available. The Guide, OpenAPI, and reference describe the field as a read-only string. groupBy: stageSemanticId remains unsupported. Create and update return READONLY_FIELD, import returns IMPORT_ITEM_VALIDATION, entity batch returns BATCH_ITEM_VALIDATION, and global batch returns READONLY_FIELD for the corresponding call.

What integrators should do

Use stageSemanticId only for reads, filters, and sorting. Remove the field from create, update, import, entity batch, and global batch bodies. Choose another field for grouping.

FIX-0829-4: mailbox and org-structure node list calls work in the batch APIs

Before

A {"entity": "mail-mailboxes", "action": "list"} sub-call in POST /v1/batch answered ERROR_METHOD_NOT_FOUND, and the same list in POST /v1/mail/mailboxes/batch answered CALL_FAILED. humanresources-nodes behaved the same way. As a standalone request, GET /v1/mail-mailboxes returned the same list with data.

After

Both batch APIs return the records. Such a sub-call runs as a separate request to Bitrix24 at any limit and spends its own rate-limit quota; neighbouring calls on other entities still travel in one batch. The record count on these two entities always arrives, even with withTotal: false. The get action on them still does not answer with data inside a batch — read the record through its own route. Details are in the "Known specifics" section of the "Batch operations" page.

Separately, the message text of a failed sub-call changed across all batch calls, not just for these two entities. It used to carry the platform's internal diagnostic; now only text that came from Bitrix24 is published, and everything else gets a fixed Internal error. Queue overflow, queue wait timeout and a Bitrix24 timeout no longer fall into that generic code: they arrive under their own QUEUE_OVERFLOW, QUEUE_TIMEOUT, BITRIX_TIMEOUT, ERROR_LOOP_DETECTED, RATE_LIMITED, OPERATION_TIME_LIMIT and TOKEN_REFRESH_FAILED codes, all but the last with a retryAfter field, so they can be told apart from an internal failure. The response stays 200 and the codes of the other sub-errors are unchanged.

The same rule applies when the whole batch request fails rather than one call: the text comes from the Bitrix24 response, and is fixed otherwise. The status, the code and the bitrixError field are unchanged — bitrixError arrives whenever Bitrix24 really answered, even when its answer carried no text.

Single endpoints also stopped returning internal text in one case: a TOKEN_REFRESH_FAILED refusal now carries a fixed message — a fragment of the Bitrix24 response could previously end up in it. The code and the status are unchanged.