# API changes: August 29, 2026

[← Changelog](/docs/changelog) · [August 2026](/docs/changelog/2026-08)

### 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](/docs/infra/app-runtime).

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

> Old format supported until: not provided

**Before**

[GET /v1/leads](/docs/entities/leads/list), [POST /v1/leads/search](/docs/entities/leads/search), and [POST /v1/leads/aggregate](/docs/entities/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.