API changes: July 2, 2026

← Changelog · July 2026

NEW-0702-1: filter and sort tasks by real status (realStatus)

GET /v1/tasks, POST /v1/tasks/search and POST /v1/tasks/aggregate now accept realStatus in filter (list and search also in sort) — filtering by the task's actual stored status: 1 — new, 2 — pending, 3 — in progress, 4 — awaiting control, 5 — completed, 6 — deferred, 7 — declined. Previously filter[realStatus] was silently ignored and the request returned the whole set.

Unlike filter[status], which Bitrix24 treats as a virtual (meta) filter (values −1 overdue, −2 unviewed, −3 almost overdue) that does not match the status field value in the response, realStatus filters by the stored status. The field is read-only (change the status via status) and is used only in filter/sort — the response already exposes the task's real status in the status field.

FIX-0702-2: creating an app reuses a failed slot with the same name

Before

Repeating POST /v1/infra/servers with the same name after a failed deploy created a new app slot. Failed slots piled up and were only removed by auto-cleanup after 7 days.

After

If the key owner already has a slot with the same name in the account in error status (or one that was created but never received a deploy), the repeated call returns that same slot: its id is preserved, the error and build log are reset, and the status goes back to provisioning — deploy into it. Slots that never received any code are now removed by auto-cleanup after 24 hours instead of 7 days (slots with a failed build are still kept for 7 days together with their build log).

Impact on integrators

No request changes are required. If your flow re-created a slot with the same name after a failure, you will start receiving the previous id instead of a new one — this is expected: deploying into the returned slot works as usual. Slots owned by other users of the account and running apps are never picked up for reuse.

FIX-0702-3: read-only keys can no longer write through /v1/bots

Before

A read-only API key (accessMode: READONLY) could perform write operations through the bot endpoints (POST /v1/bots, sending and deleting messages, adding chat members, registering and deleting a bot, and others) — the call returned 200 instead of 403. Every other Bitrix24 proxy surface already blocked such writes.

After

A write through /v1/bots/* with a read-only key returns 403 with code WRITE_BLOCKED_READONLY_KEY. Read operations are unaffected, including fetching a message context (GET /v1/bots/:botId/messages/:messageId/context) and downloading a file (GET /v1/bots/:botId/files/:fileId).

Impact on integrators

If your bot integration needs to write, switch the key to read+write mode in the /keys section.

FIX-0702-4: folders include=storage now resolves

Before

GET /v1/folders/:id?include=storage (and the list form GET /v1/folders?parentId=...&include=storage) did not add _included to the response, even though GET /v1/folders/fields advertises includable: true for the storage relation.

After

The related storage now resolves: the response includes _included.storage with the storage record looked up by storageId. The relation is described in GET /v1/folders/fields.

FIX-0702-5: PAGE_BACKGROUND_WORKER: bind no longer fails with 500

Before

POST /v1/placements/bind for the PAGE_BACKGROUND_WORKER placement filled in the options.errorHandlerUrl field Bitrix24 requires only when the call went through an OAuth session. When an app bound via a developer key or on a self-hosted portal, the field was not added and Bitrix24 answered 500 (BITRIX_UNAVAILABLE, "Field errorHandlerUrl is empty"), even though other placements bound fine.

After

For PAGE_BACKGROUND_WORKER the options.errorHandlerUrl value now defaults to handler regardless of the bind path. An explicit options.errorHandlerUrl still takes precedence. The response options field now reflects the effective value (with the defaulted errorHandlerUrl).

Impact on integrators

No action required — a call that previously returned 500 now succeeds.

FIX-0702-6: POST /search reports missing required parameters with a clean error

Before

POST /v1/{entity}/search for entities whose Bitrix24 list method requires mandatory parameters did not check for them and forwarded the request to Bitrix24 as-is. A raw Bitrix24 error leaked out (BITRIX_ERROR, e.g. "Invalid value of parameter [ $id ]" or "required parameter type is not set"), whereas the equivalent GET list already returned a clear 400 MISSING_REQUIRED_PARAMS in the same case. Affected POST /v1/calendar-events/search (needs type), POST /v1/files/search (needs folderId) and POST /v1/folders/search (needs parentId).

After

POST /v1/{entity}/search validates the required parameters before calling Bitrix24 — the same guard the GET list has had for a while. A missing parameter returns 400 with code MISSING_REQUIRED_PARAMS and the list of missing fields, with no call to Bitrix24. The required parameter can be passed inside filter, and the parent parameter (folderId for files, parentId for folders) may also be passed at the top level of the request body.

NEW-0702-7: Research price in the key self-description and the required top-up in the 402 body

GET /v1/me now returns cost for every provider in the webResearch.providers[] block, mirroring the webSearch block. The field carries the research-mode price in Ꝟ (cost.research) and the currency (cost.currency), so an agent sees the deep-search price directly in the key self-description, without a separate call.

The 402 response on insufficient balance (INSUFFICIENT_BALANCE, as well as BILLING_FROZEN) on POST /v1/search and POST /v1/research now carries a required field — the amount in Ꝟ needed for the request. The existing userMessage and hint fields are unchanged.

Clients with strict additionalProperties schema validation need to account for the new response fields.

NEW-0702-8: POST /v1/triggers/fire supports invoices (SmartInvoice)

The POST /v1/triggers/fire endpoint accepts a new entityType value — invoice. Pass entityType: "invoice" and the invoice entityId (returned by GET /v1/invoices) to fire an automation trigger for a smart invoice. Existing values (deal, lead, contact, company, quote, item) keep working unchanged.

Previously firing a trigger for an invoice was impossible, and trying it through entityType="item" with entityTypeId=31 was rejected with a message that led to a dead end. Now item with a reserved entityTypeId (including 31) points to the matching entityType — for invoices, that is invoice.

NEW-0702-9: GET /v1/ai/usage returns transcribed audio duration per model

GET /v1/ai/usage now returns an audioSeconds field in the byModel[] block — the total number of audio seconds sent for transcription per model over the selected period. The field is populated for speech-to-text (Whisper) calls and is 0 for text models, where audio duration does not apply.

The field is additive — existing integrations keep working unchanged.

BC-0702-10: categories: code and isDefault marked read-only (were phantom-writable)

Old format supported until: 01.10.2026

Before

GET /v1/categories/:entityTypeId/fields advertised code and isDefault as writable (readonly: false), but writing them via crm.category.add/update was silently ignored (values not persisted, 200 returned).

After

Both fields are marked readonly: true. /fields now reports them as read-only, and an attempt to write code or isDefault returns 400 READONLY_FIELD instead of silently dropping the data.

What integrators must do

Previously, sending code/isDefault in a POST/PATCH /v1/categories/:entityTypeId body was accepted (200, values silently ignored). Now such a request returns 400 READONLY_FIELD. Remove code and isDefault from your category create/update request bodies — these fields are no longer accepted on write.

BC-0702-11: telephony-lines: crmAutoCreate normalized to boolean and now listed in /fields

Old format supported until: 01.10.2026

Before

GET /v1/telephony-lines/fields returned only number, serverName, name. The CRM auto-create flag leaked into list responses under the raw UPPER name CRM_AUTO_CREATE as a "Y"/"N" string — the only UPPER field among camelCase ones — and was absent from /fields. On write, camelCase crmAutoCreate was silently dropped.

After

The field is declared as crmAutoCreate (boolean). It now appears in /fields, comes back normalized (true/false) in list responses instead of raw "Y"/"N", and is accepted as a camelCase boolean on create/update (the raw UPPER name is still accepted on write for compatibility). Clients reading data[].CRM_AUTO_CREATE should switch to data[].crmAutoCreate (boolean).

NEW-0702-12: workgroups: aggregate operation and groupBy fields exposed

Before

POST /v1/workgroups/aggregate worked but was never advertised: the operation was missing from the machine index at /v1/guide, and groupBy returned 400 on any field (Available: .) because the aggregatable list was empty.

After

An aggregatable list is declared: membersCount (numeric sum/avg/min/max) plus categorical active, isProject, ownerId for grouping. The operation is now visible in /v1/guide and /fields, and groupBy over these fields works.

FIX-0702-13: /fields: metadata completeness for doc-templates and bookings

Before

GET /v1/doc-templates/fields omitted isDefault and productsTableVariant even though they appear in list responses. On GET /v1/bookings/fields the mandatory resourceIds and datePeriod were not flagged required, so their obligatoriness was invisible in the schema.

After

doc-templates: isDefault and productsTableVariant are declared (read-only) — /fields now matches the responses. bookings: resourceIds and datePeriod are marked required: true, so the requirement is visible in /fields.

FIX-0702-14: orders: /fields synced with responses, pseudo-key order removed, companyId filterable

Before

GET /v1/orders/fields carried a spurious pseudo-key order (an artifact of parsing sale.order.getFields) and omitted fields that actually appear in responses: companyId, clients, dateMarked, personTypeXmlId, statusXmlId, version. Because companyId was not in the schema, filtering by it failed with UNKNOWN_FILTER_FIELD.

After

/fields is now built from the schema: the order pseudo-key is gone and the six missing fields are declared (companyId — writable number; clients — read-only object returned by get; dateMarked/personTypeXmlId/statusXmlId/version — read-only). Filtering and sorting by companyId now work.

FIX-0702-15: users: limit > 50 now honored, meta.hasMore is accurate

Before

GET /v1/users?limit=500 returned only 50 records even though meta.total reported more. meta.hasMore was always false, so the documented hasMore-based pagination silently dropped everything past the first page.

After

The entity is backed by the legacy user.get method (no .list suffix), so the auto-paginator never engaged. A paginateViaStart flag was added (same as departments): for limit > 50 it now walks pages via start, and meta.hasMore reflects whether more records actually exist.

FIX-0702-16: POST /v1/batch rejects disabled write operations and forwards required list parameters

Before

A global POST /v1/batch call with action create, update or delete for an entity whose operation is disabled (for example openline-configs — writes live behind dedicated routes) went straight to Bitrix24, bypassing normalization, and could silently create or modify a record. Separately: action list or search for an entity with required method parameters (for example calendar-events — type and ownerId) returned AUTO_PAGINATION_FAILED "missing required parameter", even though a direct list request with the same parameters worked. In addition, batch list for folders and files sent the parent folder under the name parentId or folderId, which the disk.folder.getchildren method ignores, so the list silently came back for the wrong folder; and batch list for calendar-events with a leftover filter key forwarded it to Bitrix24 with no error, so the method returned the whole calendar.

After

A disabled write operation in a sub-call is rejected with ACTION_NOT_SUPPORTED before any Bitrix24 call — the same as POST /v1/{entity}/batch. Required list parameters and the method's top-level parameters are forwarded to Bitrix24 under their original names, so batch list behaves like the direct list, and when they are missing a clear MISSING_REQUIRED_PARAMS is returned instead of a raw Bitrix24 error. For folders and files the parent folder is now renamed to the id key the method expects, so batch list comes back for the right folder. For entities whose method has no filter envelope (calendar-events), a leftover filter key is now rejected with UNSUPPORTED_FILTER before any Bitrix24 call — the same as the direct list.

Integrator impact

No action needed. If a batch sub-call previously relied on a disabled write operation running, switch it to the entity's dedicated route. For batch list on entities with required parameters (calendar-events), pass type and ownerId in the sub-call params. If a calendar-events batch list used filter, drop it or move it to the top-level parameters, otherwise the sub-call returns UNSUPPORTED_FILTER.

NEW-0702-17: GET /:entity/fields now returns field label and description

The GET /v1/{entity}/fields response can now carry a human-readable short name label and an explanatory description per field — previously a field was described only by the {type, readonly} pair. This lets an AI agent or UI show a field's name and purpose without consulting the documentation. The text is returned in English. The keys were added for the following entities: Departments, Smart Processes, Storages, Folders, Files, Workgroups, Document Templates, Bookings, Calendar Events, Tasks, Requisites, Users. For Users the label resolution was additionally fixed: GET /v1/users/fields now returns the real Bitrix24 field names from user.fields instead of the technical codes. The change is additive: the new keys appear alongside the existing ones, and existing calls keep working unchanged.

FIX-0702-18: a vibe:*-only key now issues instead of failing

Before

Issuing an API key via POST /v1/keys whose every requested scope is an internal Vibecode vibe:* scope (for example only vibe:infra), on a dev-key portal (self-hosted Bitrix24 or a connected cloud portal), was rejected with 502 DEVKEY_MINT_FAILED. vibe:* scopes are never sent to Bitrix24, so the Bitrix24 webhook scope set came out empty and Bitrix24 rejected the mint, requiring at least one scope.

After

A vibe:*-only key now issues successfully. No Bitrix24 webhook is created for it — none is needed, such a key never calls the Bitrix24 REST — and the key works with Vibecode's internal features per its scopes.

Impact on integrators

No action required: the request that previously failed now returns the created key.

FIX-0702-19: /v1/storages pagination — limit over 50 returns all records, meta.hasMore is correct

Before

GET /v1/storages with limit over 50 returned at most 50 records, and meta.hasMore was always false — even when the account held more. A client requesting ?limit=50 against 489 storages saw hasMore: false and could not tell it needed to fetch the next page. Same on POST /v1/storages/search and in /v1/batch.

After

limit over 50 goes through auto-pagination (like every other list) and returns the requested number of records, and meta.hasMore equals (offset + returned count) < meta.total even for limit of 50 or less. The change applies to GET /v1/storages, POST /v1/storages/search and the storages list in /v1/batch.

Note: the correct meta.hasMore calculation for list responses with limit of 50 or less now applies to all entities (GET /v1/{entity} and POST /v1/{entity}/search), not only storages — previously meta.hasMore was always false on this path.

FIX-0702-20: infra: Cyrillic in displayName on application create

Before

On POST /v1/infra/servers with a Cyrillic displayName, the name could be stored as a run of question marks (??????) — an encoding corruption while sending to Bitrix24.

After

The name is transmitted as UTF-8 and Cyrillic is preserved correctly.

Impact on integrators

No action required. Cyrillic names are no longer mangled.

FIX-0702-21: items: filtering by parentId relation fields

Before

Filtering by a dynamic relation field (for example parentId2 — the linked deal) on GET /v1/items/:entityTypeId and POST /v1/items/:entityTypeId/search was rejected with 400 UNKNOWN_FILTER_FIELD, even though the field is present in GET /v1/items/:entityTypeId/fields and returned in responses.

After

Fields shaped like parentId<N> are accepted in the filter and forwarded to the request as-is. Finding a smart-process item linked to a specific parent entity now works directly through the items wrapper.

Impact on integrators

No action required. Requests that previously returned 400 now succeed.

FIX-0702-22: smart processes: enumeration values and the userfield display name now persist

Before

On POST /v1/items/:entityTypeId/userfields an enumeration field (userTypeId: enumeration) was created but its value variants were not saved (the list came back empty), and a display name passed as a plain string stayed blank in the interface.

After

Value variants are accepted both as enum and as list and are saved correctly. A name passed as a plain string is automatically wrapped into a language map and fills the edit-form, list-column and list-filter labels.

Impact on integrators

No action required. The enumeration values and the name that were previously dropped silently now persist.

FIX-0702-23: req-family: address and preset-field /fields now return camelCase keys

Before

GET /v1/addresses/fields and GET /v1/requisite-presets/:presetId/fields/schema returned the field description with raw UPPER_SNAKE_CASE keys (TYPE_ID, ADDRESS_1, FIELD_NAME, IN_SHORT_LIST), even though the data of these entities (GET /v1/addresses, the preset field list) already came back in camelCase — the schema did not match the real field names in the data.

After

Both endpoints normalize the description keys to camelCase (typeId, address1, fieldName, inShortList), like the rest of V1. The inner field descriptors (type, isRequired, isReadOnly, title) are unchanged.

Impact on integrators

The /fields response keys now match the field names in the data. A client that read the camelCase names from the data gets a consistent schema; no action required.