Vibecode API Changelog

Vibecode API change history: new features, fixes, and breaking changes. Entries are ordered newest to oldest.

Entry prefixes

• NEW — a new capability: a new endpoint, a new optional field or parameter, a new error code in a new scenario. Existing client requests keep working.
• FIX — corrected behavior. The response changes to the correct one, no client action required.
• BC — a breaking change. Requires client action. The old format is supported for the stated period, then discontinued.

Entry code format: {TYPE}-{MMDD}-{N}, where MMDD is the publication date and N is a running number within that date.

Some NEW entries are marked rolling out: the method shipped in a specific Bitrix24 update and is not yet available on every portal. Until the update reaches a portal, the call returns 422 METHOD_NOT_YET_AVAILABLE with the target version — this is a sign of the rollout, not an integration error.

2026-09-10

BC-0910-1: a network failure on the way to the provider arrives under its own code ai_provider_network

Old format supported until: not provided

Before

When the platform could not connect to the model cluster, or the connection dropped before its response, POST /v1/chat/completions, POST /v1/embeddings and POST /v1/audio/transcriptions answered 502 with the general code ai_provider_unavailable — the same code as an error the cluster itself answered with. The two cases could not be told apart by the response code.

After

The same 502 response carries the code ai_provider_network. The server_error type and retryability are unchanged. This response carries no providerStatusCode field: the cluster never answered. The code ai_provider_unavailable stays reserved for the cases where the cluster did answer with an error. The original status arrives in providerStatusCode whenever the cluster answered with an HTTP status — including a refusal to open the stream after the stream itself has already started. The field is absent where there was no status: the error arrived as a frame from the body of an already open stream (such a frame carries the field only under the code rate_limit_exceeded) or the failure happened while processing the cluster's response. In streaming mode the same code arrives in the error frame before data: [DONE], together with the retryable and retryAfter fields. Speech recognition reports a network failure under the same code ai_provider_network.

What integrators should do

A client that decides on a retry by the 502 status, the retryable field or the server_error type changes nothing. A client that recognises a network failure by the code ai_provider_unavailable adds the code ai_provider_network to that check. The previous code is not returned in this scenario from the release on: there is no transition period, because one response cannot carry two codes.

FIX-0910-2: AI provider errors now carry the pause from the provider's own header, in one shape for every stream

Before

When the model cluster answered 429, the pause handed to the client was taken from the text of the cluster's response, and with no number in the text a fixed ten seconds was used. The cluster's own Retry-After header was lost. In the streaming mode of the Cowork/Code fallback model a provider error arrived as the frame { "error": { "message": "fallback stream error", "type": "server_error" } } without the code, retryable, retryAfter and providerStatusCode fields, so a cluster refusal on a rate limit was indistinguishable from its internal error. A { "error": … } frame that the cluster sends inside an already open stream reached the client as an ordinary response fragment, and the call was journaled as successful.

After

The pause is taken from the cluster's Retry-After header. The synchronous rate_limit_exceeded response carries it in its own Retry-After header, the streaming one in the retryAfter field of the error frame before data: [DONE]. A number from the response text and the default value are used only when the header is absent. The error frame of the Cowork/Code fallback stream is built the same way as the frame of the main stream: the code, type, retryable, retryAfter and providerStatusCode fields are present under the same rules. An error frame that arrives inside an open stream becomes the platform's standard error frame: the response remains a stream, after the fragments already delivered a frame with code, type, retryable and retryAfter arrives, then data: [DONE], and the call is journaled as an error. A frame raised from the body of an open stream carries providerStatusCode only under the code rate_limit_exceeded: from the body the platform accepts the status 429 alone, and the other body errors arrive under ai_provider_unavailable without that field. A refusal by the cluster with an HTTP status while opening the stream arrives as an ai_provider_unavailable frame with providerStatusCode, exactly like the synchronous response.

Impact on integrators

Nothing needs to change. A client that already reads the Retry-After header and the retryAfter field receives a more accurate pause. A client of the Cowork/Code fallback stream can now tell refusals apart by code and providerStatusCode, exactly as in the main stream.

Affected endpoints: POST /v1/chat/completions, POST /v1/embeddings, POST /v1/audio/transcriptions.

FIX-0910-3: MCP tools mark API refusals as errors

Before

Outside entity tools, an API response with success: false could be returned as an MCP result without an error flag.

After

These responses carry isError: true, including local refusals and network errors with success: false. The diagnostic JSON text is preserved. Successful responses remain unchanged and omit isError.

Impact on integrators

MCP clients that honor isError now recognize these responses as tool errors rather than successful calls. Integrations that ignore this flag and check success in the JSON text continue to work as before: the JSON format and contents are unchanged.

FIX-0910-4: the QUEUE_TIMEOUT refusal message names the actual wait

Before

In a 429 QUEUE_TIMEOUT refusal the userMessage field named 30 seconds of waiting in the Bitrix24 queue. The number was baked into the message text and did not match the wait the platform actually applied.

After

userMessage names the wait that applied to this call. The refusal still arrives with the QUEUE_TIMEOUT code, the retryAfter field and the Retry-After header — take the retry delay from those, not from the text.

Impact on integrators

No code changes are needed: the response shape is unchanged. A client that sized its own timeout by this message now reads the real queue wait limit.

NEW-0910-5: external membership is visible in V1: an external value for access.via and an externalServers block in /v1/me

The access.via field of GET /v1/infra/servers/{id} has a new value, external (alongside owner, collaborator and galaxy-reference). It means the caller was invited to this server from ANOTHER Bitrix24 account: the code surface (deploy, exec, file upload, logs, reading and downloading sources, wake) is open and listed in access.allowedEndpoints, while the owner account has no dashboard for them at all. Such a row carries its own access._note, describing the boundary of the invitation rather than development-team membership — the former shared text sent an agent looking for an interface it is not entitled to. The other values — owner, collaborator and galaxy-reference — are unchanged.

GET /v1/me now carries a new externalServers section inside data.infra, next to collaboratorServers. It lists servers on other Bitrix24 accounts the key owner was invited to as an external collaborator: total, count and items with id, name, role, companyPortalDomain (the account the server belongs to) and expiresAt (null means no expiry); items is capped at 100 rows, and total greater than count means the list was truncated. There are two sections rather than one because the credential differs: a regular key does not reach a server on another account — every external membership has its own key, which the person manages in their own account under "External access". Neither section counts towards infra.limits; those machines are not theirs.

The section is OPTIONAL: the key appears only when cross-account collaboration is enabled for the Bitrix24 account of the company that owns the server, and at least one live external membership exists for it. An absent section means "none visible", not "none exist": a row also drops out of the response when the owning company has disabled collaboration on its side, even while the membership itself is still technically live. A direct call to GET /v1/infra/servers/{id} confirms access RIGHT NOW: a 200 means membership is live AND the owning company has cross-account collaboration enabled. A 403 EXTERNAL_COLLABORATOR_NOT_A_MEMBER means "no access right now" and does not distinguish between the two possible reasons — no membership, or the owner turned collaboration off: a client cannot tell them apart today.

Both changes are additive: no existing response field is touched, and a client unaware of them keeps working exactly as before.

FIX-0910-6: X-Vibe-User-Name on a catalog open now carries the employee card name

Before

Opening an app from the Vibecode catalog put the platform account name in the header: for some employees that is a login, an e-mail address, or Unknown. Opening the same app from its Bitrix24 tile delivered the employee card name.

After

Both paths deliver the employee card name saved when the app was authorized. With no saved name the chain is unchanged: account name, then e-mail address, then Unknown.

Impact on integrators

No client change is required. For some apps the header value changes towards the employee name. The name stays a display value: use X-Vibe-User-Id as the account identifier and as the basis for access checks.

FIX-0910-7: responses of a model hosted by a third-party provider name the public model id

Before

For a catalog model hosted by a third-party OpenAI-compatible provider under a public id, the model field of the POST /v1/chat/completions response and of every stream event echoed the provider's internal model name instead of the requested public id. Provider error text named the internal name as well.

After

The model field in the response and in every stream event equals the public model id the client sent in the request, as for every other catalog model. Provider error text names the same public id. A successful response stays successful; the envelope shape is unchanged.

Impact on integrators

A client that compares model in the response with the requested id now gets a match for these models too. An integration that parsed the internal model name out of model or out of error text must switch to the public id: the internal name is no longer returned.

BC-0910-8: GET /v1/me answers 401 for a deleted key instead of 200

Old format supported until: not provided

Before

GET /v1/me returned KEY_NOT_FOUND as the body {"success": false, "error": {"code": "KEY_NOT_FOUND", "message": "Key not found"}} under status 200 OK. That was the answer to a call made with a key deleted while the request was being processed. A revoked key does not get this error — it gets KEY_INACTIVE.

After

The same refusal arrives under status 401 with the same body. The body shape is unchanged.

What integrators should do

A client whose HTTP library throws on 4xx by itself (axios with the default validateStatus, ky, got, ofetch, Guzzle with http_errors) must change its code: it no longer reaches the response body, and an exception fires instead of the branch on the success field. Handle the 401 and issue a new key on it.

A client deciding success by HTTP status (res.ok, response.raise_for_status()) used to take a deleted key for a working one and parse the refusal body as a /v1/me response. It now receives a 401 — check that the error branch leads to issuing a new key rather than repeating the same request.

A client that reads the success field from the body and does not throw on 4xx (fetch with no status check) works unchanged.

BC-0910-9: a Bitrix24 credential refusal now arrives as 401, not 422

Old format supported until: not provided

Before

When Bitrix24 rejected the credentials a key calls the account with (a revoked or expired webhook), the call answered 422 BITRIX_ERROR and the account's own code arrived in the extra error.b24Code field. On that status the refusal looked like a request-data error, so clients retried it — on a live account that added up to roughly 2,300 useless retries a day.

After

The same refusal arrives as 401 PORTAL_CREDENTIALS_REJECTED, with a hint saying a retry will not help until the key is reconnected. The code arrives on any route that reads account data, and in a POST /v1/batch sub-error. Reference — Authorization, keys and rights.

What integrators should do

If you branch on 422 BITRIX_ERROR with error.b24Code equal to authorization_error or INVALID_CREDENTIALS, move that branch to 401 PORTAL_CREDENTIALS_REJECTED and reconnect the key (POST /api/keys/:id/reconnect) instead of retrying. Other error.b24Code values in 422 BITRIX_ERROR are unchanged.

FIX-0910-10: disk move and copy operations are now available in OpenAPI

Before

Five live disk operations were absent from /v1/openapi.json and from the generated API reference cards. Four of them — moving and copying a file and a folder — were described on documentation pages, while listing the contents of a storage root was described nowhere. An agent that learns the platform from the machine schema concluded that no such methods exist. The file download card carried a separate falsehood: its summary and description promised a link, while the method returns bytes.

After

OpenAPI and the API reference cards describe POST /v1/storages/{id}/children, POST /v1/files/{id}/moveto, POST /v1/files/{id}/copyto, POST /v1/folders/{id}/moveto and POST /v1/folders/{id}/copyto — with the disk scope, the request body and the full set of refusal codes. The GET /v1/files/{fileId}/download operation declares a binary response and is described as a byte stream rather than a link. Method behavior is unchanged, a successful response remains HTTP 200, and the existing error statuses and schemas are preserved.

BC-0910-11: a custom AI provider no longer follows redirects

Old format supported until: not provided

Before

If the base URL of a custom-openai-compat provider answered with an HTTP redirect (301, 302, 303, 307 or 308), the platform followed it and sent the request to the new address. This applied to key verification, model catalog fetching and model calls.

After

The platform does not follow the redirect and returns a refusal.

• POST /v1/ai/credentials and PATCH /v1/ai/credentials/:id answer 400 base_url_redirect.
• POST /v1/ai/credentials/:id/test still answers HTTP 200 with valid: false, and data now carries a code field with the value base_url_redirect.
• POST /v1/ai/credentials/:id/fetch-models answers 400 base_url_redirect instead of a response with PROVIDER_LIST_MODELS_UNAVAILABLE.
• POST /v1/chat/completions with a model of such a provider answers 400 ai_provider_redirect_blocked, and in streaming mode an error frame with the same code arrives. Retrying the request will not help.

What integrators should do

Set baseUrl to the final API address the redirect points to. A common case is https:// instead of http://. Update an already saved key with PATCH /v1/ai/credentials/:id.

BC-0910-12: task, telephony and universal-list endpoints no longer ignore filter in silence

Old format supported until: not provided

Before

Several list endpoints answered 200 with a wider set than requested when the request carried a filter parameter, and the response gave no way to tell an applied filter from a discarded one.

The first cause: the two spellings of filter are written by the query-string parser into the same place, so the second one replaces the first. ?filter[AUTHOR_ID]=1&filter= left an empty value, which read as "no filter", and Bitrix24 was called without one: GET /v1/tasks/{taskId}/comments, GET /v1/calls/statistics, GET /v1/lists/{iblockId}/sections and GET /v1/lists/{iblockId}/elements. For the same reason a condition spelled with brackets deeper than two levels (?filter[a][b][c]=1) never reached the filter parameter at all.

The second cause: endpoints that have no filter neither read nor rejected the parameter — GET /v1/tasks/{taskId}/history, GET /v1/tasks/stages/{entityId}, GET /v1/tasks/{taskId}/checklist, GET /v1/lists and GET /v1/voximplant-lines.

After

A filter envelope from which at least one condition you spelled did not reach the parameter is rejected with 400 and the code INVALID_FILTER, before the Bitrix24 call. A condition is lost when both forms are mixed in one request (in either order), when two spellings address the same condition (?filter[a]=1&filter[a][b]=2), and when bracket nesting goes deeper than two levels — the query-string parser does not assemble that. The error text names which of these happened. Pass the whole filter in a single form, spell every condition once, and stay within two levels.

Endpoints that have no filter answer 400 with the code UNSUPPORTED_FILTER and name what to use instead: field for task history, sort and offset for the list of universal lists.

An empty ?filter= still means "no filter", and the response remains 200. Untouched on endpoints that do support a filter: a filter in a single form whose every bracket condition reached the parameter — all brackets or one JSON object — the named parameters field, sort and start, and a repeated ?filter=a&filter=b, where the parser keeps the last value — provided that value is NOT empty. An empty ?filter= standing last overwrites the previous condition, and such a request is refused.

Two caveats, so that list reads honestly. On endpoints that have no filter at all, any meaningful filter is refused, a single-form one included. And a request where the bracket form follows an empty ?filter= (?filter=&filter[ID]=1) used to answer 200 with the filter correctly applied, and is now refused as well: parameter names in a query string carry no values, so an empty spelling cannot be told apart from a non-empty one and both are refused — as has long been the case for entity list requests.

What integrators should do

1. Collapse the filter into ONE form: either all brackets (?filter[ID]=1&filter[STAGE]=NEW) or one JSON object (?filter={"ID":1,"STAGE":"NEW"}) — on endpoints that accept both. ⚠️ GET /v1/calls/statistics accepts the BRACKET form only: a JSON object is forwarded to Bitrix24 as a string and does not become a filter. Do not send an empty ?filter= next to bracket conditions, even if such a request used to work.
2. Drop bracket conditions nested deeper than two levels: the query-string parser does not assemble them, and they never reached Bitrix24 before either.
3. On endpoints that have no filter at all, switch to the named parameters the error text lists: field for task history, sort and offset for the list of universal lists.

No support window is provided: the lost half of the conditions cannot be recovered, and answering 200 to a request whose filter was not applied is the very defect being fixed.

FIX-0910-13: two spellings of one filter field no longer drop a condition in silence

Before

A field has several accepted spellings: the schema name and the Bitrix24-native name (amount and OPPORTUNITY on deals), a different case. When two conditions in one filter resolved to the same Bitrix24 filter name, the request answered 200 through a defect with a condition lost: only one of the two applied, and which one was decided by the key order in the request. The result looked filtered even though half of the filter never applied. That answer could not be relied upon — the documentation never promised it. The same happened with two spellings of one operator, with paired date field names (updatedAt/updatedTime, createdAt/createdTime, where an entity declares one of the two and accepts the other as its alias) and with synonym pairs an entity declares as separate names: on leads those are amount/opportunity, stageId/statusId, currency/currencyId.

After

Such a request is rejected with 400 INVALID_DUPLICATE_FILTER_FIELD, and message names both conditions and the shared name they resolved to. A request with a single spelling of the field answers HTTP 200 as before — the successful response is preserved. Operators producing DIFFERENT names are unchanged too: { "amount": { "$gte": 1000, "$lte": 5000 } } is a range, not a duplicate.

The result decides, not the spelling, and the two pairs have DIFFERENT boundaries. The UF_ form together with the camelCase spelling of the same custom field folds into one name only on entities with the older naming style AND only for the spelling the platform converts: the letters-only one (ufCrmProjectCode) on every such entity, and the digit-suffixed one (ufCrm_1698325419) on requisites only. On the other entities a digit-suffixed pair travels as two names, is not refused, and Bitrix24 still drops the second condition silently. On camelCase-named entities and on CRM items those are different names on the wire and nothing is refused either. $ne together with $nin on one field produces a single ! prefix on EVERY entity except CRM items — including camelCase-named ones (catalog products, mail mailboxes, smart processes); on CRM items $nin gets its own !@ prefix and the pair passes.

The rule applies to lists, search, aggregation and both batch doors; inside a batch only that call is rejected and its neighbours still run.

Affected endpoints: GET /v1/{entity} and POST /v1/{entity}/search on entities with the standard filter parsing, POST /v1/{entity}/aggregate and its legacy twin GET /v1/{entity}/aggregate, POST /v1/batch and the POST /v1/{entity}/batch sub-calls, plus GET /v1/addresses with POST /v1/addresses/search. On these doors the filter is parsed by the same code, so the refusal arrives identically.

Individual routes with their own filter format parse it with their own code and are NOT part of this change: there a pair of spellings still answers 200 with a condition lost. Those include GET /v1/requisite-links with POST /v1/requisite-links/search, call statistics, lists, task comments and the open-lines routes; the list is not closed.

Why this is a correction and not a contract change: the former 200 on such a request was never promised by the documentation and was not reproducible — it applied one of the two conditions, and which one was decided by the key order. That answer could not be relied upon, so there is no support window for the old behaviour: there is nothing to support. A request with a single spelling of the field is unaffected.

NEW-0910-14: vibe balances for every portal in one export

A new GET /v1/platform/revenue/balances returns one row per portal, as a snapshot taken at read time. Each row carries balance (the same remainder the portal sees), its composition paidRemaining + grantRemaining, the accrued shortfall accruedShortfall, overdraftLimit, billingMode, frozen, plus portalId, portalDomain, portalStatus, portalKind and accountId. The figures reconcile: balance = paidRemaining + grantRemaining − accruedShortfall.

The request takes no time window, only limit and cursor; the snapshot time arrives as capturedAt next to data. An account with no tranches is returned as a zero row instead of being skipped, so the export describes the whole portal population. This is the only surface exposing the granted remainder: GET /v1/platform/revenue/topups covers purchased tranches, so a portal with no purchases is absent from it and the welcome allocation and granted bonuses are not shown.

The method is opened by a dedicated revenue:balances scope — a key holding revenue:read gets 403 INSUFFICIENT_SCOPE on it. The existing exports are unchanged and keys with existing scopes keep working with no edits.

NEW-0910-15: companies expose their linked contacts through `include=contact`

The company entity declares a contact relation, so include=contact is now accepted on GET /v1/companies/{id}, GET /v1/companies and POST /v1/companies/search. Every record carries _included.contacts, an array of full contact records, each extended with the binding fields sort, isPrimary and roleId; a company with no linked contacts gets an empty array. Such a request used to answer 400 INVALID_INCLUDE, because companies declared no relations at all and the list of available include values was empty.

The relation also opens the binding sub-routes: GET /v1/companies/{id}/contacts lists the bindings, POST /v1/companies/{id}/contacts adds one, PUT /v1/companies/{id}/contacts replaces the whole set, DELETE /v1/companies/{id}/contacts/{contactId} unlinks one. Requests without include answer exactly as before.

FIX-0910-16: a boolean userfield flag is no longer dropped silently

Before

The userfield properties multiple, mandatory, showFilter, showInList, editInList and isSearchable are stored by Bitrix24 as the characters Y and N. Sent as booleans, they applied only half the time — within ONE request body: showInList: true and editInList: true were switched on, while showFilter: true and isSearchable: true were silently saved as off. The response was a success either way: 201 on create, {"updated": true} on update. Re-sending the same flags as booleans changed nothing: the ones that were off stayed off.

None of the six flags were declared in the API description: create listed only fieldName, userTypeId and label, and update described its body as an empty object. There was nowhere to learn the working value form.

After

All six flags are accepted both as booleans and as the strings "Y" / "N"; the platform converts either form before calling the account. The canonical forms remain a boolean and "Y" / "N"; on top of those the platform accepts the lenient spellings "y", 1, "1" to switch a flag on and "n", 0, "0" to switch it off. All of them used to travel to the account verbatim — the enabling ones did not switch the flag on and now they will; the disabling ones switched it off before and still do, so nothing changes for them. Unrecognised values pass through unchanged, as before.

Take note if your integration already sends these flags as booleans. Some of them used to do nothing and you may have grown used to that — now all of them work. Two switch-ons were measured: showFilter: true and isSearchable: true used to leave the flag off and will now turn it on. Enabling isSearchable is not cosmetic: the field's values go into the account's full-text search and start surfacing in global search.

Watch mandatory: true as well — once on, it blocks creating records without that field, including through other integrations on the account. Whether it took effect from a boolean before this change was not measured, so assume it will take effect now.

If your integration sends showFilter: "E" — the earlier table on the fixed-CRM pages called that a "mask" — the behaviour changes: such a write used to leave the filter OFF, and now it turns it ON. Among the MEASURED string values this is the only switch-over, and it is deliberate: "E" is the form the filter arrives in on a read, and sending it back must be safe.

If your integration sends "I" or "S" following our earlier table, such a write does not turn the filter on — neither before nor now. Send true to turn it on.

Check what you send before you upgrade.

The flags are now declared in the API description for both create and update. The reading quirk of showFilter is documented separately: an enabled filter comes back as E, which is Bitrix24's storage form rather than an error. The values "I" and "S" are not accepted on write and switch the filter off, so enable it with true, "Y" or an "E" you read back. The fixed-CRM reference used to describe those letters as filter modes and used them in its examples; a measurement across four field types did not confirm that, and the pages are corrected.

The round trip is closed separately: an "E" you read can now be sent straight back — the platform reads it as "on". Previously the ordinary read-modify-write cycle handed that "E" back to the account and the filter switched off silently under a success response.

The change covers the fixed CRM types — deals, leads, contacts, companies, quotes and requisites. Smart-process custom fields travel a different Bitrix24 contract and are not affected by this change.

FIX-0910-17: V1 responses return X-Request-Id

Before

The documentation asked clients to include X-Request-Id in support tickets, but API responses did not contain this header.

After

Every /v1 response produced by the backend contains a server-generated X-Request-Id. The value from a failing response can be included in a ticket together with the request time.

Impact on integrators

Existing requests require no changes. A client may save the new header for diagnostics but does not have to process it.

2026-09-09

BC-0909-1: Audio transcription retains subscription billing when Cowork/Code is disabled

Old format supported until: not provided

Before

When Cowork/Code was disabled, requests to POST /v1/audio/transcriptions using an already-issued vibe:cowork key bypassed subscription quota, even with an active subscription and an audio price configured for an available model. Exhausting subscription quota did not prevent a successful HTTP 200 response.

After

Disabling the product does not change billing: with an active subscription and a configured per-minute or per-call audio price, usage counts toward its quota, just like chat. When a quota window is exhausted, the request receives HTTP 402 cowork_quota_exhausted with a Retry-After header. Without an active subscription, the existing billing path is preserved without drawing on subscription quota.

Integration changes

Handle HTTP 402 cowork_quota_exhausted even while the product is disabled: wait for the quota window to reset according to Retry-After or upgrade the subscription tier. The key and request format do not need to change.

NEW-0909-2: Connector catalog method identifiers support Unicode

GET /v1/onec/tools and POST /v1/onec/tools/{method}/call support method identifiers containing Unicode letters, combining marks and numbers, plus ._-. The limit is 100 UTF-16 code units. Pass the exact catalog identifier in the URL using encodeURIComponent(method): case and Unicode representation are preserved. Existing ASCII identifiers continue to work.

BC-0909-3: Universal lists: an absent list answers "not found", and a bad offset answers with an error

Old format supported until: not provided

Before

The same absent list answered differently depending on which address was called: the element list, the field list, the field-type set, a single element, a single field and element files all answered 422 with a Bitrix24 message — an "something went wrong" error rather than "no such list". A read-then-create-if-missing flow broke on that.

Paging through those same lists accepted any offset. start=-5, start=abc, start=1.5 and start=1e2 were not refused: the offset was either silently dropped or applied distorted (1e2 became 1, so the second record arrived instead of the hundredth). The response was 200, so a mistake in the calling code stayed invisible — while the neighbouring parameters of the same request, iblockTypeId and sort, are refused with a clear message.

After

An absent list answers 404 with error code LIST_NOT_FOUND on the six addresses where Bitrix24 reports it with a machine code. An offset is accepted only as a non-negative integer in plain notation; anything else is refused with 400 and error code INVALID_PARAMS, and the message names the parameter that did not fit. Both start and offset are checked, even when the precedence between them is won by the first.

What integrators should do

If your code treated a 422 from the list collections as "the list is gone", switch it to 404. What is recognized is Bitrix24's machine code, not the message text, so the answer does not depend on the account language. The code itself was measured on the international platform: if your account reports an absent list differently, the recognition does not fire and the answer stays as it was. If the offset came from an external source and could arrive negative or fractional, an error now arrives instead of a page: fix the source rather than the walk. One input deserves a separate mention because it used to be understood CORRECTLY: ?start=+5 — a plus in a query string decodes to a space, and the old parsing read that as 5. It is now refused. If your builder encodes with a plus, drop it: ?start=5.

Separately, about writing parameters with square brackets. ?start[]=7 and ?iblockTypeId[]=lists used to pass: the platform joined such a list into a single value and carried on. That is now refused — brackets mean a structure, and these parameters do not take one. If your request builder adds brackets to every list by habit, send these three parameters as a plain value: ?start=7, ?offset=7, ?iblockTypeId=lists. Bracket shapes with a name inside (?start[x]=1) used to break the request with an internal error; now they get a clear refusal instead.

One more parameter belongs to the same row — the returned field set: ?select[x]=1 used to break the request with an internal error, and now the set is simply not applied and the full field list arrives; empty entries such as ?select[]=&select[]=NAME no longer travel to the account as an empty string.

The same applies to the request body when creating a section or an element: "iblockSectionId": [5] used to be read as the number five and placed the record under that parent; the value is now dropped and the record lands at the root. Send a number, or a string holding one.

The infoblock type in the body narrowed the same way but answers differently: "iblockTypeId": ["lists"] used to pass (the list was joined into a single value), and now 400 with error code INVALID_IBLOCK_TYPE arrives on the eight addresses that read this parameter from the body at all: creating and updating a list, a field, a section and an element. Deletions do not take it and are untouched. Send a string: "iblockTypeId": "lists".

What this does not change

Reading the sections still answers with a complaint about a wrong infoblock type, and reading the list itself still answers with a permission refusal when the list id is numeric. With a symbolic id that same address already answered "not found" before this change: there Bitrix24 returns an empty result rather than a refusal. Bitrix24 reports an absent list on those addresses in the same words it uses for a genuine permission refusal and a genuinely wrong type, so recognizing them as "not found" would hide real refusals.

BC-0909-4: phantom contacts field removed from companies, leads, and deals

Old format supported until: not provided

Before

Field schemas and company, lead, and deal responses could contain contacts, although the field could not be read reliably from Bitrix24. An explicit select: ["contacts"] was accepted with a 200 response.

After

contacts is no longer published in field schemas or returned in records. An explicit select: ["contacts"] without * or UF_* is rejected with 400 UNKNOWN_SELECT_FIELD. Requests for all fields through * or UF_* still succeed, but contacts is removed from the response.

What integrators should do

Remove contacts from explicit select lists. Use contactIds for company contact relations, and contactId plus contactIds for leads and deals.

Affected endpoints: GET /v1/companies/fields, GET /v1/leads/fields, GET /v1/deals/fields, read and write operations under companies, leads, and deals, POST /v1/batch, POST /v1/{entity}/batch.

FIX-0909-5: a self-hosted portal now issues a key that needs no webhook

Before

On a self-hosted portal whose owner has no developer key, issuing or rotating a key carrying only vibe:* scopes (for example vibe:infra + vibe:storage) answered 400 BOX_NO_DEVELOPER_KEY, even though no incoming webhook is registered on the portal for such a key at all. It affected POST /v1/keys, POST /v1/keys/{id}/rotate and the personal key issued for a Cowork application.

After

A scope set with no Bitrix24 scope is checked before the self-hosted guard: the key is issued, webhookUrl stays empty and the portal is not called. The 400 BOX_NO_DEVELOPER_KEY refusal stays in force for sets carrying at least one Bitrix24 scope — such a key does get a webhook, and nothing but the owner's developer key can remove it. Rotation adds one more condition: the previous row must carry no webhook. A key with no Bitrix24 scope that still has one on record answers with the same 400 — nothing can remove that webhook without the developer key, and a successful answer would hide that the old access keeps working.

FIX-0909-6: replacing an application key no longer hands out an already-expired secret

POST /v1/cowork/applications/{id}/key copied the lifetime of the replaced key onto the new one verbatim. When that lifetime had already ended, the owner received a secret that passed no request at all, while the expired key it replaced was given another 24 hours and started working again.

Before

An application whose key expired three days ago. The response is 201 with issued: "rotated", key.expiresAt holds the same past date, and previousKey.graceUntil points 24 hours ahead of the replacement.

After

The response is still 201 with issued: "rotated". key.expiresAt is counted afresh from the lifetime configured on the portal (the same value GET /v1/cowork/applications/defaults reports as keyExpiresInDays), so the new key works. previousKey.graceUntil never exceeds the replaced key's own expiry: on an expired key it stays in the past, and the 24-hour grace does not revive it. A lifetime that is still running, and the absence of one, are carried over as before — a key with no expiry stays without one, a live expiry is repeated verbatim.

The same correction to the grace period applies to POST /v1/keys/{id}/rotate: rotating a key whose lifetime had ended no longer grants the replaced key another 24 hours of service.

FIX-0909-7: a public numeric address in baseUrl and proxyUrl is no longer refused as private

Before

POST /v1/ai/credentials and PATCH /v1/ai/credentials/{id} carrying a public numeric address in baseUrl or proxyUrl — http://203.0.113.10:8080, say — answered 400 with code BASE_URL_PRIVATE or PROXY_URL_PRIVATE. Storing such a credential was only possible by writing the same address as a domain name.

After

That request now succeeds, exactly as it does for a domain name. A private numeric address still answers 400 with the same codes: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 0.0.0.0/8, and for IPv6 ::1, ::ffff:, fc00::/7 and fe80::/10. For numeric addresses only, that list now also covers the reserved ranges a numeric address could never get through before: 192.0.0.0/24, 198.18.0.0/15, 224.0.0.0/4, 240.0.0.0/4 (including 255.255.255.255), and for IPv6 fec0::/10, ff00::/8 and 100::/64. For domain names the set of refused ranges is unchanged: a name pointing into any of those reserved ranges keeps working, and a request carrying a domain name still succeeds as before. The exception is addresses that wrap IPv4 in an IPv6 form (::a.b.c.d, NAT64 64:ff9b::/96, 6to4 2002::/16): those are refused the same way whether they are written as numbers or a domain name points at one.

FIX-0909-8: the spec declares the 429 refusal of endpoints that carry their own rate limit

Before

Twenty-eight operations carry their own rate limit and answer 429 RATE_LIMITED once it is spent, while the public GET /v1/openapi.json spec did not declare that response for them. A client generated from the spec treated 429 as an undescribed status and built no retry branch at all. Affected: POST /v1/batch, GET /v1/bots/:botId/events, GET /v1/chats/recent, POST /v1/chats/events/subscribe, GET /v1/connect/authorize, POST /v1/connect/token, POST /v1/connect/revoke, GET /v1/app/blueprints/:slug, GET /v1/me/sources, POST /v1/feedback/attachments, GET /v1/platform/coupons/campaigns, GET /v1/platform/coupons/campaigns/:slug, GET /v1/workday/records and fifteen infrastructure endpoints — POST /v1/infra/servers, GET /v1/infra/servers/:id/ssh, POST /v1/infra/servers/:id/reboot, PATCH /v1/infra/servers/:id/sleep, PATCH /v1/infra/servers/:id/port, POST /v1/infra/servers/:id/wake-schedules, PATCH /v1/infra/servers/:id/wake-schedules/:scheduleId, DELETE /v1/infra/servers/:id/wake-schedules/:scheduleId, POST /v1/infra/servers/:id/sources, POST /v1/infra/servers/:id/exec, POST /v1/infra/servers/:id/upload, POST /v1/infra/servers/:id/icon, GET /v1/infra/servers/:id/logs, POST /v1/infra/servers/:id/deploy and POST /v1/infra/servers/:id/unstick. Separately, POST /v1/platform/coupons/issue did declare its 429, but named it with the code RATE_LIMIT_EXCEEDED, which the platform never sends.

After

Every one of these operations declares its 429 in the spec, and coupon issuance now names the real code RATE_LIMITED. The description sends you to the x-ratelimit-limit response header for the value in force and to Retry-After for the retry delay. No figure is written into the spec, deliberately: the header is the only source that cannot drift from the configured value. For POST /v1/infra/servers, POST /v1/infra/servers/:id/upload and POST /v1/infra/servers/:id/deploy a second code is named on the same status — DEPLOY_BACKEND_BUSY, which arrives when every slot for an inline request body is taken, refuses that one body rather than the caller, and carries Retry-After: 30. General information about limits stays on the limits page.

Impact on integrators

Neither the limits nor the behaviour of the endpoints changed, and no request needs editing. A client generated from the spec before this change is worth regenerating — 429 handling then appears where the refusal used to arrive as an undescribed status. Check the code-matching branch on coupon issuance if it was written against the spec: the server answers RATE_LIMITED.

FIX-0909-9: an expired OAuth user token returns an authentication error

Before

When an application could not refresh an expired user token, the Bitrix24 expired_token rejection was returned by the V1 API as 422 BITRIX_ERROR, which incorrectly indicated invalid request data.

After

A single V1 API call returns 401 TOKEN_EXPIRED with a hint to re-open the application from the Bitrix24 menu. In a batch request, TOKEN_EXPIRED appears in the individual call's error while the overall HTTP response remains 200. See API errors.

FIX-0909-10: the token endpoint's rate-limit refusal is now machine-readable

Before

When the platform-edge rate limiter fired, POST /v1/connect/token returned an HTML page and set no Retry-After header. An application could neither parse the body nor learn how long to wait. For the device code sign-in this is the only rate-limit refusal a live poll actually reaches.

After

The same refusal now arrives with a body in RFC 6749 form — {"error":"slow_down","error_description":"..."} — and with a Retry-After header naming the minimum pause in seconds. The form matches the one the endpoint already declares for its other refusals, so an off-the-shelf OAuth library parses it with no extra work. The response status stays 429, so a rate-limit refusal is still distinguishable from the authorization states, which arrive with code 400. Existing calls keep working.

Important: this route has two rate limiters and their bodies differ. Only the platform-edge limiter answers in the RFC 6749 form described above. The endpoint's own limiter answers with the same 429 status but in the general API envelope — { "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } } — so a branch of the shape «on 429, parse the body and compare error against slow_down» recognises only half the refusals and takes the other half for an unknown error. Tell the two apart by the X-RateLimit-Limit header: the platform-edge refusal does not carry it, the endpoint's own refusal does. The Retry-After value is a minimum pause, not a promise that the next request is accepted, so an application needs to grow its own pause as well. Both refusals and both bodies are described in Partner Connect.

FIX-0909-11: model reasoning for Cowork no longer appears in final text

Before

When Cowork did not send an explicit reasoning setting, a model could return internal working text as a regular part of the final answer.

After

POST /v1/chat/completions applies the model-declared default reasoning setting to keys with the vibe:cowork scope. Reasoning stays in its separate channel, while distinct final answer text is preserved. The response remains HTTP 200.

Impact on integrators

No client changes are required. Calls without the vibe:cowork scope retain their previous behavior.

BC-0909-12: box top-ups now check out at the licence's own till

Old format supported until: not provided

Before

A box licence issued outside the installation's default region was pointed at its single default till: no other box till existed, so the platform deliberately resolved such a licence to the default region. The purchase did not go through there anyway — the till rejects a licence key from another region — so the path ended in a dead end with no explanation.

After

Where a country's own box till is open, checkout goes to that country's site in its own currency — prices, currency and the checkout URL come from the licence region's block. While a country's catalogue has no box items, top-up for such clients is refused with a clear message instead of pointing them at a till that would reject the purchase anyway. Once the items appear, checkout switches on by itself — no release needed.

Additionally, on installations whose catalogue carries more than one currency: a payment whose currency differs from the order's is now held for review instead of silently closing the order. Where the catalogue has a single currency this does not apply.

GET /v1/cowork/subscription/preview returns the licence country's currency for such a licence.

What to do

Read the currency from the response instead of assuming the default one: currency on packages and at the response root may now be the licence country's, and null while top-up is unavailable there (topUpAvailable: false). Amounts are in that currency's minor units — converting them as if they were the default currency yields wrong numbers.

Handle the BOX_TOPUP_NOT_AVAILABLE refusal on POST /api/billing/topup-init and the unavailable flag in the catalogue: they are returned while the country's catalogue has no box items. Previously this case returned a checkout URL for the default till — the purchase did not go through there anyway, so it can no longer be treated as a working one.

2026-09-08

FIX-0908-1: warehouses no longer substitute a different id, and refuse an unsupported filter out loud

Before

A warehouse id in the request path was read leniently: GET /v1/warehouses/12.5 was not rejected but quietly became 12, so a read, an update or a delete landed on a different, genuinely existing warehouse and looked like a success. 12abc, 1e2, 007, an id with a space and an id beyond integer precision behaved the same way, and the same lenient reading applied to productId and limit. The filter[] parameter on the warehouse list, on warehouse stock and on the stock totals was not read at all: any condition — an invented field name as well as a real one — was silently ignored and the full list came back. In the API description seven warehouse operations and the aggregation operation declared success as their only outcome, and warehouse deletion was declared as a 200 response although it answered an empty 204.

After

A warehouse id, productId and limit are accepted only in canonical form — digits only, no sign, no leading zero, no fraction, no exponent, and within integer precision. Anything else is refused with 400 INVALID_PARAMS before Bitrix24 is called, so a typo in the id can no longer reach someone else's object. A filter[] passed to the three endpoints above is refused with 400 UNSUPPORTED_FILTER listing the keys received, instead of a full list that looked filtered. Requests with a canonical id and without filter[] work as before, and their successful 200 response is unchanged. The API description now carries the real refusal codes (400, 401, 403, 404, 422) for the warehouse operations and for aggregation, and warehouse deletion is declared as 204 — the response it was already sending.

BC-0908-2: A value of the wrong type in a write field is refused instead of silently corrupting data

Old format supported until: not provided

Before

A field declared as a number in the entity schema accepted any string: {"amount":"one hundred"} on POST /v1/deals answered 201 while the amount was stored as zero — Bitrix24 casts a non-numeric string to 0. On update this erased an already-stored amount: a PATCH with an unparsable value answered 200 and zeroed the field. Every other numeric field in the registry behaved the same way (sort on catalogs and products), boolean fields accepted any word, and the color string field on order statuses was silently truncated at the database column width.

After

Such a value is refused with 400 and error code INVALID_PARAMS before any call reaches Bitrix24: a numeric field accepts a JSON number or a numeric string using . as the decimal separator; a boolean accepts true/false and the recognized string forms ("yes"/"no", "y"/"n", "1"/"0", "true"/"false"); a string field with a declared length limit accepts a value within that limit. The priority and status fields on tasks accept only the values listed in their enumeration.

What integrators should do

Send monetary amounts as a number or as a string using a dot: 1234.56, not "1234,56" — a comma decimal separator is refused with an explicit error rather than quietly reinterpreted. Review places where values arrive from external systems as strings: such a request used to answer with success while the data was lost, and now returns an error naming the field.

FIX-0908-3: Paging through recent dialogs no longer loses or repeats records

Before

GET /v1/chats/recent forwarded the page size and offset to Bitrix24 as they were, where they bound an internal table join rather than the dialog count. A page could return fewer records than requested while promising another one; the last record of a page arrived with its chat and last-message fields empty; and neighbouring windows overlapped, so a offset += size walk returned some dialogs twice and missed others.

After

The page is read with headroom and sliced on the Vibecode side: a window holds exactly the number of fully populated records requested, under-populated rows are not returned, and the has-more flag is computed from the window actually served. A window past the end of the list comes back empty and no longer promises another page. A request that names no page size now returns 50 records — the size used to be Bitrix24's to choose and is now stated explicitly.

A caveat about deep windows: the overlap protection holds while offset plus page size stays at or below 190 — the window together with the headroom for under-populated rows has to fit inside one Bitrix24 page, and that page is 200 records. Past that the offset is forwarded to Bitrix24 and, on very long lists, neighbouring windows may overlap again — a limitation of the method itself, not of the platform.

What integrators should do

Nothing: the requests are unchanged and the response is now honest. If your code de-duplicated dialogs by hand, that workaround is no longer needed.

BC-0908-4: Fields that Bitrix24 assigns itself are now declared read-only

Old format supported until: not provided

Before

Five fields were declared writable and accepted with 200/201, but Bitrix24 never stored them — the value stayed empty, and the response gave no way to tell that apart from a successful write: the origin identifiers on sales pipelines, the owner module on document templates, and the problem flag with its reason on payments when updating.

After

These fields are declared server-assigned: a write attempt is refused with 400 and error code READONLY_FIELD before any call reaches Bitrix24, and the field description states plainly that the platform sets the value. The payment problem flag and its reason are still accepted when creating a payment — only the update path, where the value was lost, is closed. The pipeline origin identifiers were not declared in the schema at all and were picked up as writable; they are declared now and refused.

What integrators should do

Remove these fields from an update request body. The platform stamps the template module itself, the pipeline origin identifiers are never persisted, and the payment problem flag should be set when the payment is created.

FIX-0908-5: search and aggregate answer with an error on a wrongly typed parameter instead of silent emptiness

Before

In the body of POST /v1/{entity}/search, the limit and select fields accepted a value of any type. A non-numeric limit (for example "abc") produced HTTP 200 with an empty record list and meta.hasMore: true at the same time — a client paging while the platform promises more went into an endless loop, receiving neither a record nor an error. A select value that was neither a string nor a list of strings turned into a field name such as "999" or "[object Object]", travelled to Bitrix24 and came back as HTTP 502 with the code BITRIX_UNAVAILABLE — the platform reported its own unavailability where the fault was in the client request.

In the body of POST /v1/{entity}/aggregate, the groupBy field was checked only when it arrived as a string or a list of strings. A number, a boolean or an object was dropped silently: the answer came back as HTTP 200, without the groups key and without a warning — the client asked for a breakdown, received the overall total, and had no way to notice.

The meta.total key of list answers carried a fabricated number on pages beyond the collection, growing together with the offset: on a portal holding five storages, GET /v1/storages?offset=100 answered total: 100, and GET /v1/storages?offset=1000 answered total: 1000.

After

A wrongly typed limit is refused with INVALID_LIMIT, a wrongly typed select with INVALID_SELECT_TYPE, and a wrongly typed groupBy with INVALID_PARAMS; all three refusals arrive as HTTP 400 and name the type that came in. A numeric limit behaves as before, including the string spelling of a number ("50"), while null, an empty string and an empty list still mean "parameter not supplied" and are not errors.

The meta.total key is withheld when the page is empty and the offset is above zero: nothing can vouch for a count there, and the description of the field already warns that the key may be absent at a non-zero offset. Wherever the page is non-empty or the offset is zero, meta.total arrives as before, and the response remains HTTP 200.

FIX-0908-6: task favorites, comments and time entries answer honestly

Before

Adding a task to favorites and removing it from them answered 200 with success: true even for a task that does not exist: Bitrix24 confirms that action for any identifier while saving nothing. The 404 TASK_NOT_FOUND promised by the API description never arrived.

The task comment list ignored offset on a request without a filter and with a sort by identifier — the same page came back at any value — and meta was counted over raw chat messages. On a task whose slice held only system notifications the answer was data: [] together with total: 1 and hasMore: true, so a while (hasMore) offset += limit walk never finished.

Addressing a checklist item or a time entry that does not exist answered 422 BITRIX_ERROR carrying the internal Bitrix24 exception text (TASKS_ERROR_EXCEPTION_#512; …; 512/TE/ITEM_NOT_FOUND_OR_NOT_ACCESSIBLE), and on the time route that text spoke about a checklist.

The from and to parameters of GET /v1/task-time were not validated: ?from=notadate silently returned the whole range with status 200, as if no period had been requested.

After

Before adding to or removing from favorites the service checks that the task exists and is accessible to the key, and answers 404 TASK_NOT_FOUND when it is not. On a task that exists the response remains 200. Rate limiting and an authorization failure are not substituted by "not found".

The comment list honours offset on every read path, and meta.hasMore and meta.total are counted over comments rather than raw chat messages: a slice of only system notifications reads further, and hasMore: false with total: 0 means there are no comments.

A missing checklist item and a missing time entry answer 404 NOT_FOUND — without the internal Bitrix24 text and in terms of the requested resource. The code is declared in the API description for every method that addresses a single record.

An unparseable from or to answers 400 INVALID_PARAMS before Bitrix24 is called; YYYY-MM-DD and ISO 8601 are accepted. An empty value still means no filter. The API description of GET /v1/tasks/{taskId}/comments now declares the limit and offset it actually reads.

BC-0908-7: Lead conversion stamps backlinks and answers in the standard read format

Old format supported until: not provided

Before

POST /v1/leads/{id}/convert answered 200, but the deal, contact and company it created carried no link back to the lead they came from: filtering deals by lead returned nothing, and a deal could not be traced to its source. The response itself came in raw Bitrix24 shape — upper-case underscored keys and stringified numbers — the only such response among the routes of this section: the platform read the created records through legacy methods whose field names did not match the schema, so the values bypassed normalization.

After

Every created record gets a link to the source lead, and the lead itself gets links to the contact and company that were created (only to those actually created). The response is read through the same method as an ordinary read of a deal, contact or company, so its shape matches GET /v1/deals/{id} and its neighbours — field names in the platform's usual style, numbers as numbers.

What integrators should do

If your parsing of the conversion response was written for the raw Bitrix24 shape, switch it to the ordinary read format used by every other route of this section. The backlinks only add data and break nothing: filtering deals by lead now finds the created deal.

BC-0908-8: a payment currency that disagrees with the order is no longer swapped silently

Old format supported until: not provided

Before

Creating a payment accepted any currency with 201, while Bitrix24 stored the payment in the currency of its order — the requested one was dropped without a word. The field description meanwhile promised a free choice with a pointer to GET /v1/currencies, so the discrepancy only surfaced during reconciliation.

After

When currency is passed and does not match the currency of order orderId, the request is refused with 409 and error code CURRENCY_MISMATCH before any call reaches Bitrix24; the message names both currencies and the order. A matching currency is still accepted, so a payment read and sent back whole keeps working. The same rule applies to batch payment creation. When the order currency cannot be read, the request is let through rather than refused.

What integrators should do

Either omit currency entirely to inherit the order currency, or send exactly the one the order carries: GET /v1/orders/:id shows it.

NEW-0908-9: the standalone server auto-sleep policy is now visible through the API

POST /v1/infra/servers returns the saved data.sleepAfterMinutes for every successful create, reuse, and idempotency replay. This is a response field, not a new create parameter. A successful standalone deploy returns the same policy snapshot in data.sleepAfterMinutes, while SSE returns it as sleepAfterMinutes in the done event. For a regular standalone server that is not covered by agent/bot idle-sleep protection, a numeric timeout with no enabled recurring wake windows appends an entry starting with AUTO-SLEEP POLICY: to warnings[] with two choices: a wake window for a task that finishes before the timeout, or a deliberate always-on mode. A window only wakes the server and does not keep a background process running. The existing successful slept: false, reason: "WAKE_IMMINENT" outcome of POST /v1/infra/servers/:id/sleep-now is now documented for an imminent wake window. The HTTP 200 response itself is unchanged.

BC-0908-10: writing an amount to a smart-process type without product rows no longer answers with a false success

Old format supported until: not provided

Before

POST /v1/items/{entityTypeId} and PATCH /v1/items/{entityTypeId}/{id} accepted opportunity and isManualOpportunity on any smart-process type and answered 201/200. When the type has product rows disabled (isLinkWithProductsEnabled: false), Bitrix24 does not store those fields — the amount was silently lost while the caller saw success and moved on.

After

The platform compares what was requested against the re-read record — it already re-read it before responding, so no additional Bitrix24 calls were added. When the request EXPLICITLY asked for manual mode (isManualOpportunity: true) and did not get it, the answer is 422 AMOUNT_NOT_APPLIED: error.details.unappliedFields lists the fields that were not applied, and data carries the actual state of the record that was already created or updated. An amount sent WITHOUT that flag is not checked: from the response it is indistinguishable from a legitimate recalculation from the product rows, which works as documented — so those requests answer exactly as before. The check does not touch deals, leads, invoices or quotes — those always have product rows.

FIX-0908-11: the host from galaxyId is now available for reading

Before

The Galaxy application creation response already contained galaxyId, but GET /v1/infra/servers did not show that shared host, and GET /v1/infra/servers/:id answered 404 NOT_FOUND to the same API key.

After

Both GET operations return a limited host projection with access.via: "galaxy-reference". It contains only safe read fields. Host management and application operations still require a resource managed by the current key.

Impact on integrators

Requests require no changes. A client using the newly visible shared host should check access.via: galaxy-reference means read-only access.

NEW-0908-12: key issuance now says whether the key got access to Bitrix24 data

POST /v1/connect/token now returns an optional b24_credentials field, and GET /v1/cowork/me the same object as b24Credentials. It answers whether the issued key can read Bitrix24 account data: ready: true — the rights work, ready: false — they do not, and a reason from a closed set comes with it (WEBHOOK_NOT_CONFIGURED, WEBHOOK_MINT_FAILED, WEBHOOK_MINT_REFUSED_BY_PORTAL, INT_TARIFF_REQUIRED, VIBE_SCOPES_ONLY), plus an upgradeUrl for the reason that names a paid plan. The 401 TOKEN_MISSING body already carries the same set, so a client parses it with one branch of code.

Why it exists. A key is issued even when the account refuses to connect it to its own data: the key still works for AI calls, while every request for account data answers 401 TOKEN_MISSING. Until now a client only found that out by hitting it, and could not tell a missing right from a network failure. The state now arrives together with the key and can be re-read at any time from GET /v1/cowork/me.

The field is additive: the other fields and the response status are unchanged, and requests that ignore it behave exactly as before. It is absent where the question does not apply — for example an app key, whose account tokens are stored separately.

FIX-0908-13: workday history is returned while a day is still open

Before

GET /v1/workday/records answered 502 BITRIX_UNAVAILABLE whenever the page contained a record of a workday that was not finished yet. Such a record carries no end time, no duration and no approval flag, and the endpoint required those fields to be filled in, rejecting the whole page — including the closed days that arrived in the same response. In practice every employee currently at work got an error.

After

The record of an unfinished day is returned as is, together with the rest of the page: the HTTP 200 response is unchanged and the closing fields arrive exactly as Bitrix24 sent them. The checks that keep a wrong answer from passing silently are untouched: the page is still rejected when a record belongs to a different employee or carries no valid start time, which is what tzOffset is derived from. No client action is required.

NEW-0908-14: agents are available for Open Channel binding

Added GET /v1/agents: the method returns agents owned by the API-key owner and the bitrixBotId value accepted by welcomeBotId in an Open Channel configuration. agentId is not used for a Hermes agent; queue continues to contain human operator IDs.

NEW-0908-15: department include in user records

The include=department parameter adds an _included.departments array to a user record with the full records of every department referenced by departmentId. A user without a department returns an empty array. The request requires the user and department scopes.

Affected endpoints: GET /v1/users, GET /v1/users/:id, POST /v1/users/search

NEW-0908-16: labels and descriptions for every basic field

In GET /v1/{entity}/fields responses, every declared basic field now has a localized label and description: Russian for Russian-language portals and English for international portals.

NEW-0908-17: protection against writing over newer sources

POST /v1/infra/servers/{id}/sources accepts an optional X-Parent-Version: v<N> header — "this is the version I edited". If the latest version has moved on by the time the write lands, it is refused with SOURCE_VERSION_CONFLICT (409) and error.details.latestVersionId names the current one (null when the server has no live versions at all). A malformed header value is 400 INVALID_VERSION_ID. Without the header the endpoint behaves exactly as before.

"Current" here means the newest LIVE version — the same one that heads the version list and can be downloaded, so the version named in the refusal can always be fetched and the write retried. Deleted versions do not count, though their numbers are never reused. Deduplication is no exception: an archive byte-identical to an existing version is refused with 409 too if the head has moved on.

The guarantee runs in a single direction: your write will not land on top of a newer version. The reverse half does not exist — sources saved from the browser come from the deploy auto-save, which has no parent to declare, so a later browser deploy can still save over yours. The refusal is decided in the same place the version is created, so two uploads declaring the same parent cannot both win, and the refused archive does not stay in storage.

The POST /v1/cowork/deploy-key response gained two fields about the move onto the fresh key: repointTruncated — not everything moved, the remainder goes on the next call, and applicationSlotBlocked — an application card stayed on its previous key because the fresh key's slot is taken by another card. Previously a partial outcome was visible only in the platform's own journal.

Affected endpoints: POST /v1/infra/servers/{id}/sources, POST /v1/cowork/deploy-key

NEW-0908-18: replace an application key in one call, and see its mask on the card

An application can be added to Cowork/Code from the catalog — created earlier, on another machine, or before the Code tab existed. Such an application has no raw key and none can be recovered: the platform stores only a hash. There was nothing to publish with.

The new POST /v1/cowork/applications/{id}/key brings an application key into working order in one call. An empty personal-key slot gets a key issued, an occupied one gets it replaced; issued (minted or rotated) says which happened. The raw key is returned once, as it is on application creation. Idempotency-Key is required, and a replay answers rawApiKey: null with KEY_NOT_REPLAYABLE. If the request failed AFTER a key was issued (a 500 naming orphanKeyId), that Idempotency-Key is spent for good: repeating it answers IDEMPOTENCY_KEY_ALREADY_USED rather than minting a second key. Read the card, then retry with a NEW Idempotency-Key. One case apart: when the key was issued but the card could not be read afterwards, the answer is still 201 with the secret, application arrives null, and warningCodes carries APPLICATION_CARD_UNAVAILABLE. Read the card with GET /v1/applications/{id} — there is no reason to lose the only copy of the secret over it.

The previous key is not revoked immediately: it gets a one-day expiry, so a publish already in flight finishes. previousKey.graceUntil names the moment it stops authenticating. The request body accepts syncServerEnv: true — the platform then swaps the key in the deployed server's environment and restarts the application, and envSync reports the outcome: updated, no such line in the file, server asleep, restart failed, and so on. Without it the application keeps the old key and starts getting refusals a day later.

Refusals arrive as distinct codes rather than a generic 400: NOT_APPLICATION_OWNER — the application belongs to someone else; KEY_ROTATE_OAUTH_APP_KEY, KEY_ROTATE_SYSTEM_KEY, KEY_ROTATE_LIVE_OAUTH_GRANT, KEY_ROTATE_NOT_ACTIVE — the key in the slot cannot be replaced, the code says why; KEY_ROTATE_KEY_VANISHED — the key was removed while the request was in flight; KEY_LIMIT_REACHED — the key quota is spent; APPLICATION_KEY_REPLACE_IN_PROGRESS — a replacement for this application is already running. One replacement per application at a time, whatever Idempotency-Key the second request carries: otherwise both would issue a key and the slot would go to whichever finished last. A replacement abandoned by a crashed request stops blocking after two minutes.

On an empty slot the issue goes through the platform-wide access gate, like every other key-issuing door: an account without access gets a 402. A rotation deliberately does not — it carries the previous key's rights forward and creates none, and an owner whose access has lapsed must still be able to wind their affairs down.

The application card gained a key block: slot (auth or api — which key is shown), present, prefix, suffix, status, expiresAt, lastUsedAt, rotatable and rotateBlockedReason (whether replacement works and why not), affectsShownKey (whether it touches the very key shown). The mask is assembled client-side from prefix and suffix. The rotatable flag reports what the platform ALREADY knows, and neither side of it is a guarantee: false means "a refusal is known, and here is its reason" (rotateBlockedReason, which covers access as well as key state), true means "no known refusal". Driving the button off it is convenient — grey it out on false and show the reason — but do not turn false into a dead end: the refusal may already be gone while the card has yet to learn of it (on the lag and on the two gates outside the flag, see below). Judge by the door's answer, not by the flag alone. The block is ALWAYS there; someone the application was merely shared with receives empty fields (present: false) and rotatable: false with reason NOT_MANAGER — which means "not for you", not "there is no key". On an EMPTY slot, where the call would issue a key, the flag also covers the issuing gates: ISSUANCE_BLOCKED (the account has no platform access), INFRA_DISABLED (infrastructure is switched off), KEY_QUOTA_REACHED (the key quota is spent) and READONLY_POLICY (the account issues read-only keys only). About the CALLING key the field speaks the door's own codes, and they repeat on EVERY card of the response: INSUFFICIENT_SCOPE (the key does not carry the vibe:cowork scope) and COWORK_HARNESS_KEY_FORBIDDEN (the key was issued for an external agent). Accuracy is one-sided by design: false on an empty slot is read off the access state the platform already knows, so an account whose Bitrix24 commercial plan changed seconds ago may still show false until that state refreshes. TWO Cowork/Code gates stay OUTSIDE the field and can still refuse a call made on a true: the platform-wide kill switch (503 COWORK_FEATURE_DISABLED) and the state of your Cowork/Code seat (403 COWORK_NOT_ACTIVATED, which GET /v1/cowork/state already reports). Neither is a fact about the card itself, so neither is repeated per card — handle the door's refusal instead of reading true as a guarantee.

Affected endpoints: POST /v1/cowork/applications/{id}/key, GET /v1/applications, GET /v1/applications/{id}

NEW-0908-19: read the sprint list, active sprint, and a sprint by ID

The Vibecode API adds GET /v1/scrum/sprints for reading visible sprints, GET /v1/scrum/sprints/active for reading a project's current sprint, and GET /v1/scrum/sprints/:id for reading one sprint by ID. The response contains its name, dates, status, and project link. If no sprint is active, the active-sprint endpoint returns data: null.

BC-0908-20: a paused Cowork/Code seat no longer opens Bitrix24 past the account plan

Old format supported until: not provided

Before

A Cowork/Code desktop key and an agent key opened the Bitrix24 REST API on an account whose plan does not carry REST access, regardless of whether the seat itself was in force. A paused seat kept that ability until its key was revoked — about a month.

After

The ability follows the state of the seat. The bypass applies only to a seat in the ACTIVE state, including a seat with a scheduled cancellation, until the end of its paid term. For a paused, cancelled or parked seat the key is served by the ordinary account rule: where the Bitrix24 plan already carries REST access nothing changes, and on a plan without it the calls to Bitrix24 get the same account refusal as any other application.

What integrators should do

Resume the Cowork/Code subscription, or move the account onto a paid Bitrix24 plan. The current state of the seat arrives in the subscription.state field of the GET /v1/cowork/state response.

NEW-0908-21: ERP module tool catalog is available through the client API

GET /v1/onec/tools returns the latest validated portal tool catalog together with loaded, stale, version and update-time metadata. Each tool contains method, title, description and inputSchema. The endpoint requires the vibe:onec scope, an enabled portal connector and the RU segment, but it does not require a mapping for the current user. Before a catalog is loaded, the response explicitly contains loaded: false, an empty tools array and null revision and update-time fields.

POST /v1/onec/tools/{method}/call now accepts nested JSON values in filters: up to 200 array items, 50 keys per object, 1024 characters per string, depth 6 and 2000 nodes across the whole filters object. The keys __proto__, prototype and constructor are rejected at every level. The server continues to assign user, portal and requestId. Execution remains asynchronous: a successful request returns 202, and its result is read through GET /v1/onec/operations/{operationId}.

FIX-0908-22: the sources registry no longer advertises a door that answers 403 to the calling key

Before

GET /v1/me/sources derived reachableViaApi from ROW reachability alone — "is the server alive, is the app not deleted" — and never looked at the KEY that called. The doors its pointers lead to are key-scoped and reject an OAuth application key whenever the server belongs to someone else.

In practice: the listing enumerates snapshot owners per USER, not per key, so calling with your own application's key returned your servers created with PERSONAL keys carrying reachableViaApi: true and a working-looking listEndpoint — while GET /v1/infra/servers/{id}/sources answered that very key 403 NOT_AUTHORIZED at that very address.

The same lie appeared on application rows: the author of applications A and B, calling with the key of B, saw the row of A with a working pointer whose door answers 403 SOURCE_APP_ID_MISMATCH.

Now

reachableViaApi answers one question: will the CALLING KEY be admitted through the drill-in. A row whose door that key will not open carries reachableViaApi: false with listEndpoint and latestDownloadEndpoint set to null. Both kind branches of the listing (server and legacy-app) compute it with the same predicate the door itself uses.

The row itself does NOT disappear from the listing: a false promise was withdrawn, not visibility. The owner still sees that snapshots exist and whose they are via user.id.

What integrators should do

Check reachableViaApi before following listEndpoint or latestDownloadEndpoint. Both fields were already declared string | null and already arrived empty for an orphaned server and a soft-deleted application, and reachableViaApi: false was already a documented value for those same two cases — so a client that honoured the contract needs no change. If you get false where you expected true, you called with an application key: repeat the call with a personal key (your own or the server owner's) or with a portal administrator's key. The same holds for an application row — an application key opens only its own application.

What this does NOT change

Access. No door started or stopped admitting anyone: the access rule is unchanged, only the listing stopped promising access that was never there. Collapsing the doors of one server onto a single ownership model is a separate breaking change and ships as its own entry — and so do the publish and deploy refusal hints, because there the same address is withdrawn TOGETHER with the hint.requiredAction field, which is a documented-field removal.

2026-09-07

FIX-0907-1: redeeming a coupon on your own portal is now refused with a dedicated code

Before

POST /v1/cowork/coupon/redeem looked only at the coupon, the campaign and the seat. It did not care who was redeeming or whose portal it was: a platform employee holding the coupon-issuing right could mint a code and activate it on a portal they stand behind — the plan was granted at the platform expense, and the response was a plain HTTP 200.

After

Redemption is refused with COUPON_SELF_PORTAL (HTTP 409) when the portal is backed by a platform employee holding the coupon-issuing right — the redeemer themselves, or any portal member, API key owner or server owner on it. A successful redemption is not affected: on a portal with no such people the HTTP 200 response is unchanged, body included, and no integration work is required. The refusal does not consume an attempt against the code-guessing counter — the cause is the portal's composition, not a wrong guess. The code is listed in the endpoint's response table in the documentation.

NEW-0907-2: self-description now says whether infrastructure is stopped for non-payment

The GET /v1/me and GET /v1/cowork/state responses carry a new infraState block: frozen tells whether servers, deploy and storage are stopped for non-payment, reason is the reason code (DEBT or null), and topupUrl is the dashboard top-up address or null.

The block answers a question that had no readable source before: what exactly is stopped for an account in debt. The strings inside the block are machine-readable, and the human-facing text is up to the client.

Note that what the field means depends on whether infrastructure-debt scoping is enabled for the account (the FIX in this same release). Until it is, a negative balance refuses V1 calls broadly, GET /v1/cowork/state included; only GET /v1/me stays readable in that mode, being exempt from the freeze. There infraState.frozen means "almost everything is stopped". Once it is enabled the field means exactly what it says: infrastructure is stopped while calls within the plan monthly quota keep working.

The block is additive, existing fields are unchanged.

FIX-0907-3: fixed pagination for business process activity and automation rule lists

Before

A request with offset=50 returned the same codes as a request with offset=0. The response remained successful with HTTP 200.

After

offset skips the specified number of codes in the full list. meta.total reports the full list size, while meta.hasMore reports whether codes remain after the current page. The same behavior applies to list sub-calls for these entities in the global batch request, including both total channels. The response still returns HTTP 200, and OAuth authorization requirements are unchanged.

Impact on integrators

No action is required. Integrations using offset now receive the requested page instead of a repeated first page; the response format and authorization requirements are unchanged.

Affected endpoints: GET /v1/bizproc-activities, GET /v1/bizproc-robots, POST /v1/batch.

FIX-0907-4: infrastructure debt no longer disables what is paid for separately

Before

A negative wallet balance returned 402 ACCOUNT_FROZEN on almost every V1 call — only self-description, the guide and the support conversation were exempt — including calls that never touch the wallet: proxying to your own Bitrix24, Cowork subscription state, the model list. Debt for a virtual machine disabled AI granted by the Bitrix24 plan.

After

The account freeze applies to what the wallet pays for: servers, storage, deploy, search and research on platform credentials, spending beyond the monthly quota, deploy-key issuance and application creation. A call within the plan monthly quota, a paid Cowork subscription period and REST proxying to your own portal go through whatever the wallet state is.

Note the behaviour sits behind the wallet-debt-scoped-to-infra feature flag; with the flag off the responses are unchanged.

FIX-0907-5: an oversized numeric CRM ID is rejected before Bitrix24 is called

Before

Numeric CRM IDs were checked for shape only: any digit string without leading zeros passed the guard. This affected regular record :id values in paths (/v1/deals/{id}, /v1/contacts/{id} and similar entities), as well as positive smart-process entityTypeId values and related CRM operations. An ID beyond the safe integer range reached Bitrix24, where it could be rounded to a different value and some crm.item methods answered it with a raw PHP error instead of a clear refusal.

After

Such IDs are rejected as invalid parameters before Bitrix24 is called. The check covers regular record IDs on path and batch surfaces, as well as smart-process entityTypeId values, dynamic parameters and related CRM operations. The boundary is the safe integer: 9007199254740991 is still accepted, while 9007199254740992 and anything longer is rejected. The ID 0 remains valid wherever it was already allowed, such as the main deal pipeline.

FIX-0907-6: lead conversion respects the selected deal pipeline

Before

POST /v1/leads/{id}/convert ignored the categoryId parameter, so the new deal was placed in the default pipeline.

After

When categoryId is provided, the new deal is created in the selected pipeline immediately. The value 0 still selects the default pipeline.

A non-negative integer string remains accepted for compatibility and is normalized to a number. Other value shapes remain ignored and leave the deal in the default pipeline; null and an omitted parameter are equivalent.

NEW-0907-7: Bitrix24 employee id of the app author in /v1/apps responses

Responses of the apps family now carry two new fields: authorBitrixUserId — the numeric Bitrix24 employee id of whoever created the app — and authorBitrixUserIdSource, telling where that id came from. authorBitrixUserId is the same identifier the id field of GET /v1/users returns, so it is the join key between the two responses: an app previously carried only authorId, a Vibecode platform user identifier, with nothing to match the creator against an employee card.

Values of authorBitrixUserIdSource: member — the id comes from the author's confirmed membership of this Bitrix24 account and is safe to link; snapshot — the id comes from a value captured when the app was created, which is best-effort and may point at a different employee than the app's current author; null — the id is unknown, and authorBitrixUserId is null as well. A registry that must not be wrong should link to an employee card only on member. On self-hosted accounts and on accounts with microservice credentials the snapshot value is never returned: there the captured value has no identity-confirmed origin. Confirmed membership still works on such accounts, so the id there is either member or empty.

The author's name is deliberately NOT returned by the apps responses, which narrows the original request — it asked for the name as well. Personal data does not travel in a response every account key can read, the key embedded in a deployed application's code included; the name is fetched by authorBitrixUserId from GET /v1/users, where the user permission gates it.

Existing requests keep working unchanged: the fields are additions, nothing was removed or renamed.

Affected endpoints: GET /v1/apps, GET /v1/apps/:id, POST /v1/apps, PATCH /v1/apps/:id, POST /v1/apps/:id/publish, POST /v1/apps/:id/unpublish, POST /v1/apps/:id/relink-oauth

BC-0907-8: companies field removed from the contacts API

Old format supported until: not provided

Before

The companies field was advertised by GET /v1/contacts/fields and accepted in select for contact read operations. Bitrix24 did not return a value for this field, so a successful response could omit the companies key.

After

The companies field is no longer advertised and is always removed from contact responses. Requesting it in select is rejected with 400 UNKNOWN_SELECT_FIELD.

What integrators should do

Do not request companies. Use the companyIds field for related company identifiers.

Affected endpoints: GET /v1/contacts, GET /v1/contacts/:id, POST /v1/contacts/search, POST /v1/contacts/aggregate, POST /v1/contacts/batch, GET /v1/contacts/fields.

FIX-0907-9: multipart upload replaces a large object under its existing key

Before

POST /v1/storage/objects/multipart/create returned 409 STORAGE_KEY_EXISTS when a live app object already occupied the same key. Content larger than 10 MB therefore could not be replaced without changing the key. For a personal key, the advice to use multipart led to the same failure.

After

For an existing app object, the request returns 200 and opens a replacement session with the existing objectId. Reads return the old content until POST /v1/storage/objects/multipart/complete publishes the new bytes; a successful response confirms the new version. A confirmed POST /v1/storage/objects/multipart/abort before publication preserves the old version. If complete returns 502 STORAGE_BUCKET_ERROR, publication may have happened: that response does not identify the current version, the session remains active, and object deletion stays blocked until a platform administrator resolves it. Object visibility does not change.

POST /v1/storage/objects/multipart/create returns 409 STORAGE_KEY_EXISTS for an existing live object owned by a personal key and does not open an upload session. Delete the object first, then start a new multipart upload under the same key. This operation is non-atomic: the object is unavailable between deletion and successful completion of the new upload.

Impact on integrations

App files larger than 10 MB can be updated by multipart upload under the existing key. Multipart create, complete, and abort may return the retryable 409 STORAGE_KEY_CONFLICT when another request is changing the same key or session state changed. For create and complete, retry the same operation. A 409 from abort during finalization requires retrying complete with the same parts; if complete returns 502 STORAGE_BUCKET_ERROR, do not infer the current version and contact a platform administrator. If abort returns 502 STORAGE_BUCKET_ERROR, keep retrying abort until session release is confirmed. DELETE /v1/storage/objects/{key} returns 409 STORAGE_MULTIPART_IN_PROGRESS while a multipart session is active: complete or abort the session first, accounting for the finalization case above.

FIX-0907-10: moving a deal/lead to a nonexistent stage now returns an error instead of a silent success

Before

POST /v1/deals/{id}/move, POST /v1/leads/{id}/move, PATCH /v1/deals/{id} and PATCH /v1/leads/{id} answered 200 success:true with the full deal/lead object even when the requested stageId (or a deal's categoryId) did not exist in the reference list — Bitrix24 silently ignored the value, the stage stayed unchanged, and the caller could not tell a real move from a rejected one without manually comparing the data.stageId field.

After

The response remains 200 when the requested stage or pipeline exists and is applied — behavior for valid values is unchanged. When the requested value was not applied (Bitrix24 accepted the call but the actual stage stayed the same), the response is 422 STAGE_NOT_APPLIED with details in error.message: what was requested and what is actually there after re-reading the record.

FIX-0907-11: The placement-bind note says trial, not demo

Before

The apps.bindPlacements capability note in GET /v1/me still called Bitrix24 trial access a demo, while the refusal it describes has always been named after a trial. FIX-0904-7 settled the latin terminology on the word trial everywhere else, so this string was the last live disagreement of its kind. The same term also survived in two documentation articles — the one on starting Bitrix24 trial access, and the plan name reported by GET /v1/me.

After

The note says trial, and the documentation uses the same term. Refusal codes, statuses and response fields are unchanged, and a successful response stays successful. The note is not localised and is served identically on every installation.

Impact on integrators

None for logic. A client matching this note by substring should re-check the comparison.

FIX-0907-12: the spec declares every server mode-switch response

Before

The public spec GET /v1/openapi.json declared only 200, 400, 403 and 404 for PATCH /v1/infra/servers/:id/mode. A client generated from the spec treated the remaining outcomes as impossible, although the endpoint returned them: the exhausted-balance refusal, the server-role refusal, a parallel-request conflict and two network-policy failures.

After

The spec gains the responses the endpoint does return: 401, 402 ACCOUNT_FROZEN and OPEN_MODE_REQUIRES_COMMERCIAL, 409 SERVER_NOT_RUNNING, AGENT_NOT_CONNECTED, MODE_SWITCH_SEALED_ROLE and CONFLICT, 502 IPTABLES_FAILED, PROVIDER_NOT_CONFIGURED, GATEWAY_UNREACHABLE and TUNNEL_NOT_FOUND, 503 SECURITY_GROUP_ATTACH_FAILED and a refusal whose code starts with GATEWAY_TIMEOUT. The 400 description gains the codes SAME_MODE, NO_SUBDOMAIN and MODE_SWITCH_STANDALONE_ONLY. The same codes now appear in the endpoint page's error table: before this change it named none of the three state refusals — server not running, agent not connected, server without a subdomain. The code PROVIDER_ERROR is removed from the endpoint page's error table: a mode switch does not return it. Status 429 is deliberately left undeclared — the endpoint carries no limiter of its own, and the platform-wide edge limit is documented on the limits page rather than declared per route. Endpoint behaviour is unchanged: the successful response remains HTTP 200 with the same body, no request needs changing, and the edit touches the declaration and the documentation only.

NEW-0907-13: `/v1/cowork/me` and `/v1/cowork/state` now name the portal the key is bound to

Both Cowork/Code self-info endpoints gained a new portal field:

{
  "portal": { "id": "8f3c…", "domain": "acme.bitrix24.com" },
  "tier": "PRO",
  "state": "ACTIVE"
}

The field answers which account the rest of the body is about. A Cowork/Code seat is defined on the pair «key owner + account», and a key is bound to a single account for good, so for a person with several accounts the app reports the tier and quota of one account while the browser shows another. Until now the domain arrived exactly once, when the code was exchanged for a key (POST /v1/connect/token), and could not be asked for again.

portal.id is always present — it is taken from the key itself. portal.domain is null only in the degenerate case where the account row is already gone. Every other field of both responses is unchanged, and requests written before the field existed keep working without edits.

BC-0907-14: a partial lead conversion failure now answers 422, not 200

Old format supported until: not provided

Before

POST /v1/leads/:id/convert creates the deal, contact and company as separate records one after another. When only some of them were created, the response still arrived with status 200: the success field was false, while error, code and details sat at the top level of the body, and error was a string rather than an object. A client branching on the HTTP status or reading error.code took a partially written CRM state for a success.

After

A partial failure answers 422 with code CONVERSION_FAILED in the usual error envelope: error is an object carrying code and message. The outcome of every requested operation moved into error.details — one key per deal, contact and company, each with a success flag and either the id of the created record or the Bitrix24 refusal text. The top-level error string and code are gone from the response. A lead that could not be read answers 404 with code ENTITY_NOT_FOUND in the same envelope. A successful conversion still answers 200 with a data field.

What to do

Branch on the HTTP status and on error.code, not on the success field and not on the top-level code; read per-record outcomes from error.details rather than from details. Records already created are still not rolled back and the lead keeps its status, so before repeating a call check what already landed in CRM: a repeat creates a second set of records. There is no support window for the former 200 response: it reported success where some CRM records had not been created, so keeping it would mean going on passing a failure off as a success.

FIX-0907-15: root-type validation on entity create, update, batch and search

Before

A JSON literal null as the request body crashed POST /v1/{entity}, PATCH /v1/{entity}/{id} and POST /v1/{entity}/batch with 500 INTERNAL_ERROR; that status was not declared for any of the three routes. A JSON array or a JSON string as the body of POST /v1/{entity} created a real record with empty or auto-generated fields and answered 201, as if the request had been valid. On PATCH /v1/{entity}/{id} a JSON string passed the empty-body check and answered 200 without actually changing anything. On POST /v1/{entity}/search an array body answered 400 INVALID_FILTER_SHAPE with a message that misnamed the type actually sent (reporting a function instead of an array); a bare scalar body (a number, a string, a boolean) was treated as "no filter" and answered 200 with the unfiltered record list.

After

A well-formed body (a JSON object — for /search, including an empty {}, which is the legitimate "no filter" request) is handled unchanged. The response still remains 201 on create and still remains 200 on update, batch and search — none of that changed. A body whose JSON root is not an object (null, an array, a string, a number, a boolean) now answers 400 on all four routes, and no record is created or modified: EMPTY_CREATE_BODY on create, EMPTY_UPDATE_BODY on update, INVALID_BATCH_ACTION on the per-entity batch route, INVALID_REQUEST on search. The search error message now names the type actually sent instead of an internal implementation artifact.

FIX-0907-16: an absent record answers 404 for warehouses, catalogs, order statuses, basket items and smart processes

Before

One and the same scenario — "no record with this id" — answered with different codes inside a single product area. GET /v1/order-statuses/{id} and GET /v1/basket-items/{id} returned 422 BITRIX_ERROR, while the neighbouring orders, invoices, payments and quotes returned 404 at the same step. GET /v1/catalogs/{id}, GET /v1/warehouses/{id} and the product-property pages behaved the same way, even though catalog products and prices already answered 404. A delete-confirmation check based on the response code silently failed on those paths.

Separately, on a portal whose interface language is not Russian, PATCH and DELETE for /v1/smart-processes/{id} with a nonexistent entityTypeId answered 400 INTERNAL_ERROR — a code the DELETE contract does not even declare. On a Russian portal the same call correctly answered 404 SMART_PROCESS_NOT_FOUND, and GET was correct in every language.

After

An absent record answers 404 on all of the paths above. GET, PATCH and DELETE for warehouses, catalogs, order statuses and basket items return 404 ENTITY_NOT_FOUND; the portal text in the message field is unchanged, only the classification of the response is. The same 404 now arrives on the product-property and property-value pages.

PATCH, DELETE and POST /v1/smart-processes/batch answer 404 SMART_PROCESS_NOT_FOUND regardless of portal language, exactly as GET has done for a long time. A client can rely on one existence code across the whole Vibecode API instead of keeping per-area and per-language exceptions.

2026-09-06

FIX-0906-1: a free Bitrix24 plan now answers key issuance terminally, not with a "retry later"

Before

A cloud account on a free Bitrix24 plan could get 502 CONNECTOR_REST_UNAVAILABLE with details.retryable: true on key issuance, whenever its Marketplace access read as in force. The answer promised that a retry would help. Bitrix24 shuts REST off entirely on a free plan, so a retry never did.

The activation.marketTrial.available flag in GET /v1/cowork/state has always read false on this segment: the Marketplace trial is a subscription-region product, so POST /v1/cowork/activate-market-trial never had a one-time trial to spend here.

After

The same case answers terminally with the refusal this segment already uses for a plan that does not carry access — INT_TARIFF_REQUIRED (403) with a userMessage naming the remedy, a paid Bitrix24 plan. The code is not new; what changed is the set of states it comes in: previously only "access paid for but not in force", now any access state on a plan read as free. A retry without changing the plan returns the same thing.

activation.marketTrial.available keeps its region_not_supported reason on this segment, and POST /v1/cowork/activate-market-trial together with POST /v1/portals/{id}/activate-market-trial keep refusing exactly as before — that half of the change is region-gated above the plan check and does not reach here. An account on the Bitrix24 demo plan is not affected either: that plan does not shut REST off, so it keeps the answer it had. An account whose plan could not be read behaves as before.

BC-0906-2: PATCH /v1/infra/servers/:id/mode rejects opening a server with a sealed role

Old format supported until: not provided

Before

For a server whose role (a pool member, a service machine) requires a sealed network policy, PATCH /v1/infra/servers/:id/mode with mode: "OPEN" responded 200: the server did switch to open mode, and the issued SSH password worked.

After

Such a request is now rejected with 409 MODE_SWITCH_SEALED_ROLE; the server's mode is left unchanged and no password is issued. The rejection applies where the server's network policy is backed by the additional layer for that server; where it is not backed, behavior is unchanged.

What integrators should do

Clients that expected 200 for servers with a sealed role must handle 409 MODE_SWITCH_SEALED_ROLE as a terminal rejection: open mode is not available for such a server, and retrying will not help. For other servers (not a sealed role), 200 and password issuance are unchanged.

NEW-0906-3: PATCH /v1/infra/servers/:id/mode may return a network-policy switch failure

PATCH /v1/infra/servers/:id/mode enforces a server's network policy with one more layer — outside the guest machine, on top of the protection already in place inside it. If switching the server's network policy fails, the endpoint responds 503 SECURITY_GROUP_ATTACH_FAILED; the server's mode is left unchanged, and retrying the request makes sense. This rejection is only possible where the additional layer is supported for a given server; where it is not supported, the endpoint's behavior is unchanged.

FIX-0906-4: PATCH /v1/infra/servers/:id/mode closes the server firewall when the connection drops mid-switch

Before

PATCH /v1/infra/servers/:id/mode performs the switch by running commands on the server itself. If the connection was lost partway through that sequence — a timeout, a dropped tunnel, an unreachable agent — the endpoint returned an error, but the server could be left with its firewall already open while its mode stayed BLACKHOLE: the opening command had time to run, and nothing was left to close it again. The error, meanwhile, reported that the switch had been aborted.

After

Such a drop now triggers closing the firewall back before the error reaches the client: previously nothing was attempted on this path, and a server left open while its mode said BLACKHOLE stayed that way until someone intervened.

That closing travels over the same connection that has just dropped, so it is an attempt, not a guarantee: if the server is unreachable altogether it does not arrive either, and the discrepancy remains. The response does not report this — the outcome of the attempt is visible in the platform log.

One case is deliberately left out: if the server had already been closed and it was the mode write that failed, the firewall is NOT reopened — undoing a completed closure because of a write failure would be the more dangerous choice. The server is then closed while its mode is reported as OPEN.

What integrators should do

Response codes are unchanged, and retrying the request still makes sense. In the exception described above, retrying with mode: "OPEN" is rejected as 400 SAME_MODE — the stored mode is already OPEN; access is restored by switching to BLACKHOLE and back to OPEN.

BC-0906-5: a platform integration key now dies together with its issuer's authority

Old format supported until: 31.12.2026

Before

A /v1/platform/* key lived until someone revoked it by hand. Revoking a team member's platform tier, blocking them, or accepting an account-erasure request left the key alone: the revenue export channel and coupon batches kept working on behalf of a person the platform itself no longer admits.

After

The key is revoked automatically at the moment its creator loses platform authority — tier revocation, a block, or an accepted erasure request. Requests made with such a key receive 401. The remaining platform administrators get an email listing the revoked keys.

If the channel is still needed, issue a new key from an active team member: POST /api/platform/integration-keys. There is no way to check the channel state in advance — the email is the notification — so integrations should treat 401 as "a new key is required" rather than as a transient error.

2026-09-05

FIX-0905-1: chat with a Cowork/Code key works while the product is disabled

Before

POST /v1/chat/completions returned HTTP 503 with the lowercase code cowork_feature_disabled in the response body for an already-issued key carrying the vibe:cowork scope when Cowork/Code was disabled at the platform level.

After

The model call continues through the Cowork/Code subscription and still checks subscription activity, model availability, and quota. The switch continues to close Cowork/Code product interfaces and operations. Integrators do not need to change anything.

FIX-0905-2: the key-issuance refusal now separates an unread plan from a free one

Before

An international account whose plan Vibecode could not read was refused key issuance with 402 and the code INT_VIBE_PLUS_REQUIRED (or INT_TARIFF_REQUIRED), advising a paid plan. That advice could be wrong — the account might already be paying — because the decision was made off an empty plan code, and the code is empty both for a read free account and for one whose licence could not be requested.

After

The two states are now told apart. When the plan code is absent AND the last licence probe failed, the answer is 403 with the code PORTAL_TARIFF_UNREADABLE: the plan was not read, and buying one does not change that. details.requiredTariffs is empty — no plan clears this refusal — while details.upgradeUrl and alternatives[0].url point to support. The previous codes keep their own state: an account with a plan read as free still gets 402 and the previous copy.

2026-09-04

NEW-0904-1: asynchronous ERP tool calls and operation status

A separate Vibecode deployment, not this one, gains POST /v1/onec/tools/{method}/call and GET /v1/onec/operations/{operationId}: a tool call executed asynchronously by the account's ERP connector module and tracked as a durable operation with a status URL. The codes ONEC_USER_NOT_MAPPED and ONEC_OPERATION_GONE belong to that deployment's contract.

Nothing changes on this deployment and no action is required. The ERP connector is not part of the API served here: both URLs answer 404 for every account, whatever its configuration, no setting exists that could enable them, and neither code above is reachable here. No new field and no new branch appear in the contract you consume here.

NEW-0904-2: the Supports BitrixMobile flag at application registration

POST /v1/apps accepts an optional mobile: boolean field, defaulting to false. When true, the platform reports the Supports BitrixMobile flag to Bitrix24 at application registration on the account, and the application becomes visible in the mobile client. The mobile field now appears on the application object too — in the creation response, application data, the list and relink. Applications created earlier carry false. The flag is set only at creation — PATCH /v1/apps/:id does not accept mobile. When the account registers the application through a path that cannot carry the flag, the application is created with mobile: false and the creation response carries a warnings line starting with mobile:. Existing requests without mobile keep working. Details — Create an application.

BC-0904-3: the self-hosted refusal code is renamed to SELFHOSTED_NOT_AVAILABLE

Old format supported until: not provided

Before

A self-hosted Bitrix24 account on the international installation was refused with the code INT_BOX_PARTNER_REQUIRED. The message explained that access comes with a partner licence, that the key carried no confirmed partner mark, and asked the customer to re-register the module on the portal. The button pointed at the connect documentation: details.upgradeUrl and alternatives[0].url carried the address of /docs/connect-self-hosted-bitrix24.

After

The same refusal arrives with the code SELFHOSTED_NOT_AVAILABLE. A client that branches on the code must replace the string — the old code is no longer returned on any surface.

The rest of the response is unchanged: the status is still HTTP 402, details.requiredTariffs is still empty (no plan purchase clears this refusal), and alternatives keeps the same members in the same order.

The message and the button address changed. The message no longer names the reason and no longer asks for anything to be done on the portal: self-hosted is not available yet, access is being opened gradually, and the account's servers and data are kept as they are. details.upgradeUrl and alternatives[0].url now carry a mailto: support address — the only address where this is resolved.

FIX-0904-4: trial deployment hints account for galaxy host eligibility

Before

GET /v1/me promised one-shot deployment whenever any running or sleeping galaxy host existed. If that host could not accept the app, POST /v1/infra/servers rejected the request and its hint suggested two-step creation, which then hit the trial portal limit.

After

GET /v1/me shows the one-shot path only when a known host appears eligible and explicitly marks the prediction as advisory. POST /v1/infra/servers remains authoritative; when an ineligible host occupies the trial limit and trial enforcement is active, the response no longer recommends an unavailable two-step create.

Impact on integrators

Check deployment.galaxyApp before a one-shot create and follow error.hint after a refusal. Before using the two-step path, also check capabilities.servers.create.available and choose a plan from capabilities.servers.create.limits.allowedPlans in the same response.

FIX-0904-5: a catalog card is no longer published without its portal binding

Before

Publication could complete with b24CatalogSync.status set to SYNCED even though the catalog card had no binding to the sender. In that state, the new-version notification did not arrive in the application chat and no reason was displayed.

After

When calling POST /v1/infra/servers/:id/b24-catalog/publish, such a card is no longer created. For a paired portal, publication completes only after the card's binding to the sender has been confirmed. Until it is confirmed, b24CatalogSync.status stays other than SYNCED, pendingOp stays ADD, and lastError names the reason. The response is still HTTP 200, and a successful publication returns exactly what it returned before.

Impact on integrators

Requests do not need to change. If an integration monitors the asynchronous status, pendingOp=ADD together with a status other than SYNCED means that the card has not been published yet. Wait for the status to change or show the lastError value to the user.

FIX-0904-6: expiresAt of presigned URLs now equals their signature lifetime

Before

POST /v1/storage/objects/multipart/create computed parts[].expiresAt from the requested lifetime — 24 hours for every part — and GET /v1/apps/{id}/sources/{versionId}/download and GET /v1/infra/servers/{id}/sources/{versionId}/download from a fixed 30 minutes; the redirect link of GET /v1/storage/objects/{key} was documented as valid for 10 minutes. The currently disabled POST /v1/storage/objects answers 503 STORAGE_PRESIGNED_UPLOAD_DISABLED and computed expiresAt the same way. The URL signature could expire earlier, and storage answered 403 while expiresAt was still in the future.

After

expiresAt in these responses is taken from the URL signature itself and equals its lifetime. It may be shorter than the 24-hour multipart session and shorter than 30 minutes for download URLs; the redirect link may also expire before 10 minutes. Nothing changes for the disabled POST /v1/storage/objects: it still answers 503, and once enabled its expiresAt will also come from the signature. The response remains HTTP 200, the field format is unchanged.

Impact on integrators

Schedule uploads and downloads by the expiresAt from the response and start as early as you can, not by the uploadId session lifetime and not by the documented 30 minutes. Clients that already relied on expiresAt change nothing.

FIX-0904-7: the latin locales call Bitrix24 trial access a trial

Before

The latin locales called Bitrix24 trial access a demo, while Bitrix24 itself names it a trial on the international installation. The mismatch reached the contract too: GET /v1/me returned Demo period in data.tariff.name, and the INT_TARIFF_REQUIRED refusal told the reader to activate a paid plan "or its demo". Within a single activation flow neighbouring messages disagreed with each other: one said trial, the next said demo about the very same access.

After

The plan value and the refusal text in the latin locales are settled on the word trial. GET /v1/me returns Trial period for that plan, and the INT_TARIFF_REQUIRED refusal now offers a paid plan "or its trial". A client comparing this field by string should re-check the comparison: the codes, statuses and response fields themselves are unchanged, and a successful response stays successful. The Russian locale keeps its own wording.

This entry covers the contract: the plan value and the refusal text. At publication time the apps.bindPlacements capability note of the same endpoint and the documentation articles still said demo, and they were translated later, in FIX-0907-11.

FIX-0904-8: batch currencies sub-call no longer returns meta.total 0 next to a non-empty data

Before

POST /v1/batch with a currencies list sub-call published data.meta.<id>.total: 0 and hasMore: false while data.results.<id> held records. The Bitrix24 method crm.currency.list reports envelope total: 0 next to a non-empty result, and the batch door accepted that literal zero as the collection size. A client paging by hasMore under a limit smaller than the catalog read the first window and treated the set as exhausted, losing the tail.

After

On a counted sub-call the envelope zero no longer beats the measured set size: data.meta.<id>.total and data.totals.<id> report the size before the client-side window, and hasMore is computed as offset + returned < total, staying true while a tail remains. This matches the single endpoints, which already normalized this method behaviour. An uncounted sub-call (params.withTotal: false, a negative params.start) still gets no total, and a genuinely empty catalog still returns total: 0. The response remains HTTP 200.

NEW-0904-9: a partner application can revoke its own key

A new POST /v1/connect/revoke endpoint follows RFC 7009: the application sends client_id, client_secret (public clients send none) and token, and exactly the presented key is killed. Its slot in the user's key limit for that Bitrix24 account is freed immediately, and requests with the key start answering 401 KEY_INACTIVE.

A 200 also comes back when there was nothing to revoke — for an unknown token, for a key issued to another application and for an already revoked one — so the call is idempotent and cannot be used to probe whether someone else's keys are alive. A missing client_id or token gives 400 invalid_request; an unknown client or a wrong secret gives 401 invalid_client. A key issued before the client was deactivated can be revoked as well.

The endpoint is announced in the discovery document /.well-known/oauth-authorization-server through revocation_endpoint and revocation_endpoint_auth_methods_supported. Until now a key issued to an application could only be revoked by the user in the "Connected apps" section, by the application owner deleting the client outright, or by a platform administrator; all three keep working as before.

BC-0904-10: offset in the statuses and deal-categories references works at any depth

Old format supported until: not provided

Before

GET /v1/statuses returned the same records for offset=0, 50, 100 and 300. The Bitrix24 method behind this reference answers with the whole collection in one response and applies no navigation, while the wrapper cut that response from the beginning — the client received the first page in place of the fiftieth. At an offset that was not a multiple of 50 the window repeated with a period of 50: offset=130 returned the same records as offset=30.

An offset walk did terminate, but it collected duplicates and never reached the end of the reference: out of 267 records only about 50 were reachable through the list, while meta.total reported an honest 267. There was no error at any step — every response came back with status 200. GET /v1/deal-categories and list sub-calls inside POST /v1/batch behaved the same way.

A list sub-call inside a batch with NO explicit limit also behaved differently from the same list issued as a single request: a single GET /v1/statuses returned 50 records by default, while the batch sub-call returned the entire reference — all 267 records in one response.

After

The [offset, offset + limit) window is computed on the Vibecode side over the full set, in the order the core returned. offset=50&limit=5 yields records 51 through 55, a limit above 50 no longer truncates the tail, meta.total equals the size of the filtered set, and meta.hasMore turns false on the last page. An offset walk terminates and covers every record exactly once. The response remains 200.

A list sub-call inside a batch now follows the same default as a single request: with no explicit limit it returns the first 50 records and hasMore: true, not the whole reference.

Sorting and filtering are still performed by Bitrix24, so the sort parameter behaves as before. The same behaviour applies to POST /v1/statuses/search and to list sub-calls inside POST /v1/batch.

Impact on integrators

Loops that previously re-read the same records and never reached the end of the reference now return the full selection — they need no code change.

One case does require a code change: a POST /v1/batch sub-call listing statuses or deal categories with no explicit limit. It used to return the whole reference; it now returns the first 50 records. There is no error — the response comes back with status 200 and hasMore: true — so the remaining records are lost silently unless they are requested.

What to do: either set limit explicitly, or read the reference page by page, advancing offset by the page size until meta.hasMore becomes false. The second option is preferable — it does not depend on the size of the reference and works on any portal.

BC-0904-11: Workday history now returns the time-zone offset

Old format supported until: not provided

Before

GET /v1/workday/records required only timeman. Records did not contain a required tzOffset, so a client could not reliably obtain the employee's local time.

After

The endpoint requires timeman and one of user_brief, user_basic, or user. Every record contains a required tzOffset: seconds east of UTC calculated for the startTime instant using the historical rules of the current IANA TIME_ZONE identity in the employee profile. The value is not proof that this zone was assigned when the record was created. The startTime and endTime strings are unchanged. A non-empty page returns 502 BITRIX_UNAVAILABLE if the current profile zone or its offset cannot be determined reliably; the API cannot detect a zone reassignment after record creation and does not promise a 502 for it.

What integrators should do

Reissue existing keys with timeman and one user-family scope, then process the required tzOffset in the GET /v1/workday/records response.

NEW-0904-12: asynchronous accounting-system calls under a mapped user

POST /v1/onec/tools/{method}/call queues an operation under the current user's active mapping and requires the vibe:onec scope. The body specifies only the method, columns, filters, and pagination: the server takes the user identifier and name from portal settings, with no client override or fallback account. The 202 response contains operationId, while status and result are available through GET /v1/onec/operations/{operationId} to the same portal, user, and key.

BC-0904-13: Entity read calls now have a per-portal rate limit

Old format supported until: not provided

Before

Entity reads — list (GET /v1/deals and the same call on every entity), search (POST /v1/deals/search), aggregate (POST /v1/deals/aggregate, including the legacy GET …/aggregate), field definitions (GET /v1/deals/fields), related records (GET /v1/deals/{id}/contacts, …/activities), product rows (GET /v1/deals/{id}/products) — and the per-entity batch (POST /v1/deals/batch and the same on every entity) accepted requests without a rate limit — while the global POST /v1/batch already carried one. One client reading a list more than roughly ten times per second slowed lists and search for every portal on the same instance, up to request timeouts. A HEAD request to a list was served as a full GET: the data was read in full and only the headers were returned.

After

Every such read is capped at 300 requests per minute per portal; all API keys of one portal share one limit, and each entity and each operation is counted separately. On exceeding it the Vibecode API answers 429 RATE_LIMITED with a Retry-After header; the body carries no delay — read it from the header. The current limit value arrives in the x-ratelimit-limit header. The per-entity batch is capped tighter — 30 requests per minute per portal, the same as the global POST /v1/batch: one such request fans out into hundreds of Bitrix24 calls. The HEAD method on these paths is no longer served by the read handler — use GET with limit=1 instead. Successful responses, error codes and payload formats are unchanged.

What integrators should do

Handle 429 on every entity read and on the batch the same way as on /v1/search and /v1/batch: wait for the delay in Retry-After and retry. If the limit triggers regularly, read less often and in larger pages (limit up to 5000 per call), cache results on your side and do not run identical reads in parallel. If you probed list availability with HEAD, use GET with limit=1 instead. Make batches larger rather than more frequent: one request takes up to 500 items.

NEW-0904-14: invoices support include=deal

GET /v1/invoices/:id, GET /v1/invoices, and POST /v1/invoices/search now accept include=deal. The related deal from parentId2 is returned in _included.deal. When no relation exists, the value is null.

2026-09-03

NEW-0903-1: `GET /v1/models` exposes the reasoning control declaration

Every model in GET /v1/models and GET /v1/models/{model} now carries a reasoning field: null when no declaration is set, otherwise an object { map, default, budgetTokens } — map translates a platform step (none|low|medium|high|max) into the model's native mode, default names the step the model applies when no reasoning parameter is sent, budgetTokens — reasoning token-budget support. The field is additive: the shape of capabilities is unchanged and existing requests keep working as before. Details — /docs/ai/models/list.

NEW-0903-2: reasoning control in chat completions

POST /v1/chat/completions accepts reasoning_effort, reasoning and chat_template_kwargs, normalizes them to the five Vibecode platform steps (none, low, medium, high, max) and applies the nearest step the model supports — rounding down and never disabling reasoning without an explicit request. The response carries a reasoning field (requested, applied, native), the REASONING_EFFORT_ADJUSTED, REASONING_NOT_SUPPORTED, REASONING_CANNOT_BE_DISABLED, REASONING_BUDGET_NOT_SUPPORTED, TEMPERATURE_OVERRIDDEN_BY_REASONING warnings in warnings and the X-Reasoning-Applied, X-Reasoning-Native, X-Reasoning-Warnings headers — in streaming mode the headers are the only channel. Without the parameter in the request the body sent to the model is unchanged and the model's behavior does not change. Reasoning tokens are billed as output tokens at the same rate. Details — /docs/ai/chat/completions.

FIX-0903-3: invalid reasoning parameter values are rejected

Before

Unknown reasoning_effort, reasoning, chat_template_kwargs fields were silently dropped, and a request with a typo in the value ran as if the parameter were absent — the response was HTTP 200.

After

A value outside the vocabulary (none, minimal, low, medium, high, xhigh, max), a non-positive reasoning.max_tokens or a non-object chat_template_kwargs is rejected with 400 invalid_request in the OpenAI envelope { "error": { "message", "type", "code" } }; an explicit null in any of the three fields is accepted as "not set"; for a valid request the response remains HTTP 200.

FIX-0903-4: GET /v1/me no longer declares region as required

Before

In the GET /v1/me response, the server-create description for requests without source marked region as required and included it in the required-fields list. As a result, clients using self-discovery could require a region even though the server-create contract already allowed it to be omitted.

After

GET /v1/me marks region as optional and explains that the platform uses the selected provider's default region when it is omitted. Only self-discovery changed: GET /v1/me remains HTTP 200, while the existing behavior and HTTP 201 response of POST /v1/infra/servers without region are unchanged.

Integrator impact

Clients that build requests from GET /v1/me may stop treating region as required. Existing requests that explicitly supply a region need no changes.

FIX-0903-5: direct BOX calls honor certificate trust

Before

On a BOX portal with a trusted self-signed certificate, windowed search, file downloads, and some key operations could fail with a TLS error while regular API calls worked.

After

All these calls use the trust setting only for the exact BOX portal address. Cloud and OAuth calls, and download redirects to an external address, keep strict certificate verification.

BC-0903-6: an app key without an employee session reads only app-shared files by name

Old format supported until: not provided

Before

GET /v1/storage/objects/{key} made with an app key and no Authorization header returned an employee file when exactly one object existed under that logical name. It worked only because the name was one per app, and the behaviour could not be relied upon: as soon as more than one object held the name, the choice became arbitrary.

After

Such a request reads only the app-shared file, from the release onwards — there is no transitional mode. If the name is held solely by per-employee files, the response is 404 STORAGE_OBJECT_NOT_FOUND. The same narrowing applies to HEAD and to delete-by-name. The GET /v1/storage/objects listing is unchanged.

What integrators should do

If you read or deleted an employee file with an app key and no employee session, pick one of two: pass that employee's session in the Authorization: Bearer header, which makes their file reachable; or take the object identifier from the GET /v1/storage/objects listing and address it directly (GET /v1/storage/objects/{objectId}), a route the narrowing does not touch.

FIX-0903-7: employees of one app can save files under the same name

Before

A logical file name was one per app. If a portal employee saved avatar.png, a second employee of the same app got 409 STORAGE_KEY_OWNED_ELSEWHERE on a direct upload and 409 STORAGE_KEY_EXISTS on a multipart one — even though the files would land at different addresses, because a per-employee file address includes the employee identifier. The refusal never expired: the name stayed taken until the first employee deleted the file.

After

The name is claimed per employee. The second employee gets 200 and their own object with its own identifier; a repeated upload by the same employee still replaces that employee's own file. An app-shared file and a per-employee file share one namespace, so a request that finds the name already held by an object of the other ownership kind still gets 409 STORAGE_KEY_OWNED_ELSEWHERE.

FIX-0903-8: a multipart upload distinguishes who holds the logical name

Before

POST /v1/storage/objects/multipart/create answered 409 STORAGE_KEY_EXISTS for a taken logical name regardless of who held it — both when the object was yours and when it belonged to the other ownership kind: an app-shared file versus a per-employee file. The response could not tell those cases apart, although the actions that resolve them differ.

After

When the name is held by an object of the other ownership kind, a multipart upload answers 409 STORAGE_KEY_OWNED_ELSEWHERE — the same way a direct upload has long done. Every other taken-name case still answers 409 STORAGE_KEY_EXISTS, and the response status is unchanged in all cases.

What this means for integrators

No action is required: a refusal stays a refusal with the same 409 status, only the code in the body changes. If your client branches on the specific code of a multipart upload, add a branch for STORAGE_KEY_OWNED_ELSEWHERE — it means the name is held by an object of the other ownership kind and cannot be freed by switching employees.

BC-0903-9: smart process stage history by numeric entityTypeId, query parameters are now strict

Old format supported until: not provided

Before

GET /v1/stage-history accepted only four named types — deal, lead, invoice and new-invoice. A smart process has no name, so its stage history could not be requested at all: ?entityType=128 answered 400 INVALID_ENTITY_TYPE without ever calling Bitrix24.

The sibling parameters (ownerId, typeId, categoryId, limit, offset, createdAfter, createdBefore, stageId, stageSemanticId, statusId, statusSemanticId) meanwhile were accepted in forms that answered SUCCESSFULLY:

?entityType=deal&ownerId[]=5 returned 200 and the history of owner 5, exactly as if the value had arrived as a scalar. A repeat ?entityType=deal&ownerId=5&ownerId=6 returned 200, silently taking the last value. A repeat with identical values ?entityType=deal&limit=50&limit=50 returned 200 and a correct result set.

After

entityType accepts a smart process numeric entityTypeId — ?entityType=128. The identifier comes from GET /v1/smart-processes. Smart processes are stage-based, exactly like deals: stageId, stageSemanticId and categoryId apply, and the response carries the same fields.

A numeric identifier that already has a named key (1, 2, 31) is refused and steered to that key. Contact (3), company (4), quote (7) and the legacy invoice (5) have no stage history and are refused as well. An identifier absent from the account returns 400 INVALID_ENTITY_TYPE rather than a Bitrix24 error.

Every parameter listed above is accepted exactly ONCE and only as a single string value. All three forms from the Before block now answer 400 INVALID_PARAMS — the bracket ones (?ownerId[]=5, ?ownerId[x]=1) and the plain repeat (?ownerId=5&ownerId=6) alike, including when the repeated values are identical, and a MIXTURE of spellings (?ownerId[]=6&ownerId=5) — that last one answered 200 keeping only 5 of what was asked for. The bracket form ?ownerId[x]=1 used to answer 500.

The numeric parameters (ownerId, typeId, categoryId, limit, offset) are additionally accepted only as an integer written in full: no sign, exponent, leading zeros or suffix. ?ownerId=1e3 returned 200 and the history of owner 1 instead of 1000, ?typeId=2abc the history of type 2, and ?ownerId=abc dropped the owner filter altogether and answered WIDER than asked. All three now answer 400 INVALID_PARAMS.

The entityType forms are tightened too: entityType[]= and entityType[x]= returned 500 instead of 400; a repeated entityType=a&entityType=b silently took the last value and is now refused; entityType=constructor and entityType=__proto__ answered 200 with an empty result instead of a refusal. The INVALID_ENTITY_TYPE message now names the numeric form too, not only the four names.

The same class is closed in POST /v1/duplicates/find and POST /v1/triggers/fire: a body with a non-string type or entityType — number, object or array alike — returned 500 instead of the documented 400. In triggers/fire the same now applies to entityId and triggerId: an object in those fields either crashed the request into a 500 or reached Bitrix24 as a meaningless value and answered 200 without firing anything. A MULTI-value array in entityId reached Bitrix24 glued into one string, addressed no record and fired nothing — that is a 400 now. A ONE-value array worked ([5] was read as 5 and the trigger fired) and keeps working. Numbers are still accepted in both fields and reach Bitrix24 unchanged — a numeric triggerId that worked keeps working. A non-string entityType in duplicate search is now refused rather than ignored. Both routes also answer 400 to a request sent with no body and no Content-Type header, where they used to answer 500.

What integrators should do

Send every query-string parameter once and as a scalar value: ?ownerId=5 rather than ?ownerId[]=5 and rather than the repeat ?ownerId=5&ownerId=6. If the filter is assembled in a loop, check that a key cannot be appended to the query string twice — a stray repeat used to pass unnoticed and now answers 400 INVALID_PARAMS naming the parameter in the error text.

The old form is not kept accepted for a transition period: there is no support window and the refusal applies as soon as the update ships, so a client-side change ships together with the update rather than after it.

Clients that already send parameters as single scalars need no change.

FIX-0903-10: one request no longer pauses a Bitrix24 method with its own sub-calls

Before

When one request to the Vibecode batch and looping API methods repeatedly timed out on the same Bitrix24 method, it could trigger a 15-minute pause for that method by itself. Remaining sub-calls returned TIMEOUT_QUARANTINE, and the pause affected other requests from the same portal.

After

All sub-calls of one request now count as one attempt for each portal-method pair. Separate requests can still trigger the protective pause after the configured number of consecutive timeouts. Successful and error response formats are unchanged.

Impact on integrators

No client changes are required. The fix covers POST /v1/batch, POST /v1/{entity}/batch, GET /v1/tasks/:taskId/comments, POST /v1/tasks/:taskId/comments, POST /v1/tasks/:taskId/comments/batch, GET /v1/task-time, and GET /v1/timeline-logs.

BC-0903-11: an employee photo that cannot become a file is refused on update

Old format supported until: not provided

Before

On employee update, a personalPhoto value Bitrix24 cannot read as file content reached the portal as a command to remove the current photo. The literal false behaved that way, and so did the booleans true and false, the number 0, a string with fewer than two base64-alphabet characters — !!! or ===, for example — an inline [file name, base64] pair whose content is one of those, and any other structure whose second value is missing, null or unreadable, the nested {fileData: [...]} and an explicit null or a structure in the content element included. The call answered with success after the deletion had happened, while the earlier refusal covered only an empty or whitespace-only string.

After

Such values are refused with INVALID_PARAMS before the Bitrix24 call on all three update surfaces, exactly like the empty string. A value with two or more base64 characters still travels to the portal: it does become a file, and Bitrix24 itself decides whether that file is usable. On CREATE in POST /v1/users the new refusal does not apply.

What integrators should do

Do not put placeholders such as false, 0, true or empty strings into personalPhoto to mean "change nothing" — omit the field instead. To remove a photo, call DELETE /v1/users/:id/personal-photo.

NEW-0903-12: a command that removes an employee photo

The employee photo now has a command of its own for removal — DELETE /v1/users/:id/personal-photo. It removes the profile photo and answers 200 with the fields id, personalPhoto: null and removed: true. The call is idempotent: for an employee with no photo it succeeds as well. The operation is irreversible, Bitrix24 deletes the file itself, so uploading the same image again yields a new URL. The user scope is required, a read-only key does not run the command, and the rights decision belongs to Bitrix24 — on a refusal it answers 403 UPDATE_FAILED and the photo stays in place.

Writing the personalPhoto field removes the photo on no update surface, and null is not a way to do it either. On PATCH /v1/users/:id and in the per-entity batch, null is accepted and ignored, while the global POST /v1/batch refuses it with INVALID_PARAMS, because the sub-call encoder would turn it into an empty query-string value — the same remove-the-photo command. That difference between surfaces is now documented deliberately, and the behaviour of the calls did not change. To replace a photo you do not need a separate removal: send the [file name, base64] pair in personalPhoto to POST /v1/users or PATCH /v1/users/:id.

BC-0903-13: business process activity and robot creation returns a string code

Old format supported until: not provided

Before

POST /v1/bizproc-activities and POST /v1/bizproc-robots returned HTTP 201 with boolean data.id: true. This value could not be used as the code in PATCH or DELETE.

After

The same requests still return HTTP 201. For the regular Bitrix24 response true, data.id contains the string code submitted at creation; when Bitrix24 explicitly returns CODE, that value wins. The identifier can be used for subsequent PATCH and DELETE requests.

What integrators should do

Change the data.id type for these two responses from boolean to string and use the returned value as the code for updates or deletion.

BC-0903-14: re-uploading with a personal key now refuses where the object state requires it

Old format supported until: not provided

Before

Uploading again onto an occupied key with a personal developer key or in a server-owned context always returned HTTP 200 and created a second row, so object-state checks were never reached.

After

The repeat now goes through the same state ladder as an app-bound key, and three situations return a refusal. A different visibility on the repeat returns 400 STORAGE_VISIBILITY_MISMATCH: omit the field or pass the stored value, which is named in the message. A multipart upload (Path C) onto an occupied address returns 409 STORAGE_KEY_EXISTS before the session is created. A body with no Content-Length onto an occupied address returns 409 STORAGE_REPLACE_REQUIRES_LENGTH. 409 STORAGE_UPLOAD_PENDING and 409 STORAGE_MULTIPART_IN_PROGRESS also become reachable — for these keys they never fired before.

FIX-0903-15: re-uploading with a personal key replaces the file instead of creating a second object

Before

A personal developer key and a server-owned context created a SECOND object at the same physical address when the same key was uploaded again. The first object's bytes were overwritten by the second, its size was billed twice, and a read or delete by logical name could hit either row. The dangerous-content-type gate for PUBLIC objects was evaluated against the declared visibility, so text/html slipped in under a live public object.

After

Uploading again replaces the content of the existing object: object.id, createdAt, key, physical address and visibility are preserved, while sizeBytes, sha256, contentType and contentUpdatedAt are updated. The response remains HTTP 200. An eligible soft-deleted object is revived exactly as it is for an app-bound key. The dangerous-content-type gate is evaluated against the visibility of the row that was found, before any byte is written, so text/html can no longer land under a live PUBLIC object.

FIX-0903-16: Node.js 20 deploy no longer depends on the package repository on a prepared image

Before

The Node.js 20 preparation step always contacted the external system package repository, even when every base package was already installed. An unavailable repository left the step without updates for a long time and then failed it.

After

A prepared image with the base packages does not contact the repository. When a package is still required, the network wait is bounded; the streaming response periodically reports elapsed time during lengthy preparation. The terminal response shape and successful status are unchanged.

BC-0903-17: currency sorting rejects a field Bitrix24 cannot sort by

Old format supported until: not provided

Before

GET /v1/currencies and POST /v1/currencies/search accepted any field name in sort and order. The Bitrix24 method crm.currency.list silently replaces an unknown key with its default order, so the answer came back 200 with a list in an order the client had not asked for and with no sign of an error. The same applied to the sort and order keys of an entity=currencies sub-call in POST /v1/batch.

After

Three fields are accepted: sort, id and fullName. Any other name — the non-existent bogus as well as the declared amount — returns 400 UNKNOWN_SORT_FIELD before Bitrix24 is called, and the message lists the accepted names. The documented ?order[sort]=asc is unchanged.

What integrators should do

Three classes of change, each needing its own check.

First: a request with an unknown field name now gets 400 instead of 200. Code that relied on such a request "just working" will now see an error — that is the fix, but it has to be handled.

Second: the fields amount, amountCnt, base, formatString, decimals, decPoint, thousandsSep, lid, dateUpdate and lang also answer 400. They never sorted anything: the platform method replaced the order with its default, so the successful answer was untrue.

Third, and quietest: ?sort=id and ?sort=fullName now really change the row order while staying 200. Both used to fall back to the default order silently. A paged walk over those fields via offset will return different pages than before the update, and there is no sign of it in the response status — re-check such walks.

Affected endpoints: GET /v1/currencies, POST /v1/currencies/search and the entity=currencies sub-call in POST /v1/batch — both the sort and the order key. For other entities the batch order key still reaches Bitrix24 as-is.

BC-0903-18: include accepts only resolvable relations

Old format supported until: not provided

Before

The site relation on GET /v1/pages/:id, requisite on GET /v1/companies/:id and GET /v1/contacts/:id, and quote on GET /v1/deals/:id were advertised as available. A request with such an include returned HTTP 200 but did not add the relation to _included. The same happened to deal, contact, and company on GET /v1/quotes/:id, contact and company on GET /v1/invoices/:id, and section on GET /v1/products/:id.

After

Quote, invoice, and product relations are returned in _included as an object or null when the foreign key is empty. site on pages, requisite on companies and contacts, and quote on deals are no longer advertised. Requesting these names returns 400 INVALID_INCLUDE.

What integrators should do

For a page, read siteId and request GET /v1/sites/:id. For a company, use GET /v1/requisites with entityTypeId=4 and entityId=<companyId> filters. For a contact, use it with entityTypeId=3 and entityId=<contactId>. For a deal, read quoteId and request GET /v1/quotes/:id.

BC-0903-19: input array in POST /v1/embeddings capped at 64 strings

Old format supported until: not provided

Before

POST /v1/embeddings accepted an input array of any length — there was no limit on the number of strings in one request.

After

The input array accepts at most 64 strings. A longer array is rejected with 400 invalid_request before anything is charged and before the model is called. Split a larger request into parts of 64 strings.

NEW-0903-20: speech-to-text error texts no longer name the recognition engine

The English texts of the ai_provider_timeout and ai_provider_unavailable errors returned by POST /v1/audio/transcriptions no longer name the recognition engine; codes, statuses and the transcription contract on the international platform are unchanged.

FIX-0903-21: a Vibe+ demo now opens access on .com

Before

An account holding a Vibe+ demo kept getting INT_VIBE_PLUS_REQUIRED: granting the demo does not change the account's plan code, and the access verdict read only that code. The capabilities.servers.create slot in /v1/me stayed available: false, so retrying the action hit the same refusal.

After

A live demo opens access in trial mode, under the same limits as a Marketplace demo. A purchased Vibe+ plan on top of a live demo still grants full access, and an expired demo grants none.

NEW-0903-22: two new promo code refusal codes: Bitrix24 plan restriction

A promo code campaign can now narrow its audience by Bitrix24 plan. The restriction is a list of allowed plans; an empty list means there is no restriction — every campaign and promo code issued earlier behaves exactly as before, and a request that knows nothing about the new codes loses nothing.

When the list is set, both public promo code methods report the new codes: POST /v1/cowork/coupon/preview returns them in the reason field when valid=false, and POST /v1/cowork/coupon/redeem answers 409. There are two codes, and they must not be conflated.

COUPON_TARIFF_NOT_ELIGIBLE — the account plan has been read and is not on the list. The refusal is final: the code will not start working on this account by itself, so retrying the request is pointless.

COUPON_TARIFF_UNKNOWN — the restriction applies, but the platform has not established the account plan yet (this happens on a freshly connected account). The promo code is intact, the attempt does not consume the redemption attempt limit, and retrying later is the right action.

In both cases the promo code stays unredeemed, and the existing refusal codes are unchanged.

Important: for preview the response status is the same as before — 200 with valid=false — but the reason field now also carries these two values. A client that matches reason against a known set must add branches for them: COUPON_TARIFF_UNKNOWN falling into a default "the promo code is invalid" branch shows a final refusal where the right action is to retry later. The attempt-limit behaviour of a check is the same as that of a redemption: COUPON_TARIFF_UNKNOWN does not spend it, COUPON_TARIFF_NOT_ELIGIBLE does.

2026-09-02

BC-0902-1: Documents expose the PDF transformation status

Old format supported until: not provided

Before

The isTransformationError, transformationErrorCode, transformationErrorMessage, transformationCancelReason, and pullTag fields were not declared in the documents contract. If Bitrix24 returned them through GET /v1/documents/:id, the Vibecode API passed their values without normalization. The same fields in POST /v1/documents and PATCH /v1/documents/:id bodies were not rejected by the local read-only field validation.

After

The five fields are declared as nullable response-only fields. isTransformationError is returned as boolean | null, and the other four fields are returned as string | null. Empty strings in the string fields become null. A write request containing any of these fields returns 400 READONLY_FIELD.

What integrators should do

Do not send these five fields in document create or update bodies, including when resubmitting a previously received object. Accept null when reading the fields and use pullTag to subscribe to transformation status updates.

BC-0902-2: The mode-switch address in the access-mode refusal is no longer fixed

Old format supported until: not provided

Before

The WRITE_BLOCKED_READONLY_KEY access-mode refusal always returned details.switchUrl as "/keys", and the machine schema pinned that value with enum: ["/keys"]. The keys section lists personal keys only, so for the two other kinds the path was a dead end: neither an application auth key nor a management key is ever listed there, by construction — neither for the owner nor for the Bitrix24 account administrator. The holder was given the address of a page that carries no switch for their key.

After

details.switchUrl points at the page that switches the mode for that particular key: the keys section "/keys" for a personal key, the Applications page "/applications" for an application auth key, the management keys section "/management-keys" for a management key. The message text names the same address as the field — they are built together and cannot disagree. The value enumeration is gone from the schema: this is a UI path, not a protocol constant, and pinning a literal made the contract unsatisfiable once the page moved. The field is still always present and still required — the value changed, not its presence.

What integrators should do

Read switchUrl from the response instead of hardcoding "/keys". Clients that generate types from the schema no longer receive the literal type '/keys' — regenerate your types, otherwise value validation will fail.

FIX-0902-3: a stream that never started ends with a retryable error for models from every provider

Before

Stream setup for bitrix/* models already made a single attempt on one shared budget, while for models from every other provider the platform silently repeated the request and waited for another full budget. The client received nothing meanwhile — up to two full budgets of silence — and then saw a generic provider failure that does not tell a stalled stream setup apart from any other unclassified error.

data: { "error": { "code": "ai_provider_unavailable", "type": "server_error", "retryable": true, "retryAfter": 6 } }
data: [DONE]

After

Stream setup makes a single attempt on one shared budget for models from EVERY provider. If the headers do not arrive within it, the wait no longer doubles and the stream ends with the same stream_idle_timeout event as a stream that went silent mid-response — naming the stream itself as the thing that stalled.

data: { "error": { "code": "stream_idle_timeout", "type": "server_error", "retryable": true, "retryAfter": 7 } }
data: [DONE]

The wait no longer doubles invisibly and the reason is named precisely — now across the whole model set, not only bitrix/*.

NEW-0902-4: booking resources lookup in V1

GET /v1/booking-resources is now available — it returns the booking resources available to the key and closes the gap in the first-booking flow: POST /v1/bookings requires a non-empty resourceIds, and there was no way to learn valid identifiers through V1 alone.

The booking scope is required. A key in read-only mode works — the method is a read. The typeId and searchQuery filters are optional and may be combined, and any other parameter is rejected with 400 INVALID_PARAMS.

The catalogue is collected in full, so there are no pagination parameters: meta.total equals the length of data, and meta.hasMore is always false. Each record carries exactly four fields — id, name, typeId and isMain. The description field is withheld: it is free-form portal text and is not needed to pick a resource.

Completeness is guaranteed for a catalogue that did not change during the request — Bitrix24 provides no snapshot of the collection. An account with more than 500 resources gets 502 BITRIX_RESULT_TOO_LARGE instead of a truncated list; the same two filters narrow the lookup.

NEW-0902-5: money-in export marks revoked orders and returns the recognizable amount

In the per-payment export GET /v1/platform/revenue/money-in/payments every row now carries a revokedAt field — the package revocation date in UTC ISO-8601 format, or null for a live order. A revoked order's row does not disappear from the export and its amounts do not change: the money did arrive on the paymentDate, and cash-in still reconciles with the bank statement.

In the aggregate GET /v1/platform/revenue/money-in two nested tiers now travel alongside the previous sums. The revoked tier is the revoked part of the same values (ordersCount, grossCashRub, vatRub, netRubExclVat, vibesCredited), and the recognized tier is the same values minus the revoked part, that is the recognizable amount. Top-level fields do not change their values and remain the cash-in for the period, so existing integrations keep working with no changes.

A revocation arrives as a separate event and may happen after the period is closed, so on a repeated export a previously exported row may turn out to have revokedAt filled in. The set of rows stays the same, and the orderId key is stable.

NEW-0902-6: device-flow accepts a device identifier

POST /v1/connect/device/authorize accepts an optional device_id — a stable identifier of the client installation (up to 128 characters; letters, digits, _.:-). It takes effect for the Cowork/Code application: when the same device connects again, the previous key is revoked instead of sitting in the list next to the new one. Other clients may send the parameter, but it does not yet affect how their keys are issued.

The parameter is optional, and behaviour without it is unchanged — every connection issues its own key and earlier ones stay active. Several distinct devices for one person keep working as before: their identifiers differ, so their keys never displace each other. A value that does not match the format is ignored — the connection still succeeds, only the replacement is lost.

NEW-0902-7: new INT_BOX_PARTNER_REQUIRED refusal code for self-hosted accounts on the international installation

On the international installation platform access for a self-hosted account can require a confirmed partner (NFR) licence. A self-hosted account without that confirmation receives HTTP 402 with the new code INT_BOX_PARTNER_REQUIRED — on server, agent and managed-bot creation, and on key issuance. The refusal body is shaped like its neighbours in this family (userMessage, alternatives, hint), but details.requiredTariffs is empty: moving to another Bitrix24 plan does not clear this refusal, and the mark is read when the connector module registers. The same code appears in the reason of the capabilities.servers.create slot of GET /v1/me, and the documentation address in its alternatives[].url. The requirement is off by default and is switched on by a platform administrator; while it is off, no account sees this code and responses stay unchanged.

NEW-0902-8: stable account identifier in the key self-description

GET /v1/me returns a new field, portalId — the stable identifier of the Bitrix24 account the key is bound to. It arrives in the same request, next to the existing portal and owner, and is present for vibe_api_ and vibe_app_ keys.

Unlike the domain in the portal field, this identifier survives a rename or a move of the account. Use it whenever local data is split per account: an account key built from the domain stops matching the previous one after a move, and the data of the same account ends up in a new empty store.

In a successful response the field is never empty: a key with no account bound never reaches this response, it gets 401 NO_PORTAL. Management keys vibe_live_ do not get the new field — they are not bound to a single account and still return the list of accounts in portals.

NEW-0902-9: server creation answers 409 `REISSUE_IN_PROGRESS` while the application authorization key is being re-issued

POST /v1/infra/servers has a new refusal code REISSUE_IN_PROGRESS with status 409. The Vibecode platform answers with it when the application card owner is re-issuing its authorization key at that moment: no server is created, because it would land on a key that is being revoked in the same second.

The refusal is transient — repeat the request once the re-issue finishes. The successful response and every other refusal code are unchanged, and requests that worked before keep working.

FIX-0902-10: Open Channels dashboard methods are now available in OpenAPI

Before

Six public Open Channels statistics methods were described on documentation pages but were absent from /v1/openapi.json and the generated API cards.

After

All six methods are available in OpenAPI and API cards with the imopenlines scope, parameters, and response schemas. Runtime behavior is unchanged: a successful response remains HTTP 200, and the existing error statuses and schemas are preserved.

NEW-0902-11: support code in an unrecognized key issuance refusal

When Bitrix24 refuses to issue a key for a reason the platform does not recognize, the response now additionally carries error.details.incidentCode — a six-character support code. The platform writes the same code to the portal journal next to the refusal breakdown, so quoting it is enough for support to find the entry.

The field is optional and added to the existing response body: the HTTP status, error.code and error.details.reason are unchanged, and clients need to do nothing.

NEW-0902-12: the Performance Review section is available through /v1/performan/review

Six endpoints are now available under the new performan scope. Reads: GET /v1/performan/review/campaigns, GET /v1/performan/review/self-reviews, GET /v1/performan/review/peer-reviews, GET /v1/performan/review/manager/questions, GET /v1/performan/review/manager/reviews. Every list but campaigns requires the campaignId parameter; manager cards also accept an optional revieweeUserId filter. The response is { "success": true, "data": [...], "meta": { "nextCursor": ... } }. Pagination is cursor based: limit (1..200, 50 by default) and afterCursorId, taken from meta.nextCursor.id of the previous page. A limit outside that range answers 400. These methods have no offset parameter and no total-count field.

Every list is scoped to the calling user: their campaigns, their cards and the manager relations where they are the reviewer. An empty response means "nothing for this user", not "nothing on the account".

Write: POST /v1/performan/review/manager/answers with a body of { "relationId": 4, "answers": [...], "isAutosave": true, "expectedStateHash": "..." }. The isAutosave field defaults to true, which saves a draft; pass false to finalise the review, which moves the card to the completed status and cannot be undone. The expectedStateHash value is returned only by a write, never by a read method, so the first call goes without it. When the state changed since it was read, the answer is 409 with the PERFORMAN_STATE_CONFLICT code: re-read the card and repeat the request with the fresh value. A relation that belongs to somebody else and a relation that does not exist both answer 403. A read-only key gets 403 WRITE_BLOCKED_READONLY_KEY on the write.

The section is only available on accounts where the Performance Review module is installed and the surface is enabled for them: elsewhere all six addresses answer 404 and are absent from that account's GET /v1/openapi.json. The performan scope is withheld from the default set for the same reason.

A Cowork key gets the scope reactively: if it has not been granted yet, the first request to any of the addresses answers 409 PERFORMAN_SCOPE_JUST_GRANTED and grants the right on the spot — retry the same request and it will succeed. A read-only key does not get the right this way: the reactive grant is a write, so such a key is refused with 403 and its owner adds the scope in the dashboard instead.

A choice question cannot be answered through the API: no read method exposes option ids, and the question list returns a question without its options.

GET /v1/openapi.json now carries a rate limit per caller address. The precise cap is returned in the x-ratelimit-limit response header — read it there instead of hard-coding a value. Exceeding it answers 429 RATE_LIMITED. The cap is generous and normal reading does not reach it: the spec is served with an ETag, so a discovery client or an SDK generator gets a 304 instead of the body on a repeat fetch.

The spec body depends on the request's key: with a key of a portal the performan surface is enabled for, it carries the performan paths and the performan scope in the catalogue; without a key it does not. The response is therefore marked Vary: Authorization, X-Api-Key (the key is read from either header), and with such a key it is served as Cache-Control: private rather than public. Do not reuse one stored spec file across different keys.

FIX-0902-13: the Bitrix24 plan refusal on key issuance and app installation now states its cause

Before

When Bitrix24 refused issuance with FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN (the portal plan does not include Vibecode), the answer carried nothing actionable on ANY issuance endpoint — both where a key is issued (POST /v1/keys → 502 CONNECTOR_KEY_ISSUE_FAILED) and where an app is installed (POST /v1/apps → 502 CONNECTOR_APP_INSTALL_FAILED). The body held no human-readable text and the cause stayed in an internal field only, so clients read the refusal as a transient platform failure and retried. Retrying never helps: the gate lifts only when the Bitrix24 plan changes.

HTTP 502
{ "success": false, "error": { "code": "CONNECTOR_KEY_ISSUE_FAILED", "message": "connector refused to issue the key" } }

After

The refusal is now resolved against the portal region. Where access is on sale, the answer is 402 with a plan paywall code and human-readable text: INT_VIBE_PLUS_REQUIRED, carrying details.requiredTariffs: ["vibe+"] and a details.upgradeUrl pointing at the plan page inside the portal itself. Where there is nothing to offer (a self-hosted portal, a portal already on a paid plan, an unrecognised region), the answer stays 502 but gains its own code CONNECTOR_PLAN_REQUIRED and a non-empty userMessage instead of an empty body.

HTTP 402
{ "success": false, "error": { "code": "INT_VIBE_PLUS_REQUIRED", "message": "This action requires a Vibe+ plan on your Bitrix24 account.", "details": { "requiredTariffs": ["vibe+"], "upgradeUrl": "https://example.bitrix24.com/online/?feature_promoter=limit_why_pay_tariff_vibe" } } }

What integrators should do

Successful responses are unchanged. A client that branches on the error code now receives a terminal class instead of a transient one and can stop retrying: none of the new codes clears on a retry. A client that only looked at the status keeps working — the operation ended in an error before and still does.

FIX-0902-14: a refusal on the consent page returns the user to the partner application

Before

The user approved access, hit a key issuance refusal — no subscription, an unsupported region, the key limit used up — and stayed on the consent page. Nothing arrived at redirect_uri: the partner learned neither of the attempt nor of its reason.

After

The refusal now carries a return address: the page shows a "Back to the app" button, and redirect_uri receives error=access_denied (temporarily_unavailable when Bitrix24 is down), the machine-readable reason in error_description and the original state. If the registered return address carried a code parameter of its own, a refusal strips it — a refusal never arrives mixed with the marks of success. Refusals before the confirmation behave the same way — an expired consent link and a broken CSRF token, including on the "Decline" button.

2026-09-01

FIX-0901-1: a permission refusal on the sprint board arrives as 403, not as a platform error

Before

A key whose user has no access to the scrum project got 422 BITRIX_ERROR for the sprint board columns — the same class the Vibecode platform uses to report a Bitrix24 business error. The code gave no way to tell "no rights" from "something is temporarily off on the account", so the request was retried even though the state is stable and a retry changes nothing.

HTTP 422
{ "success": false, "error": { "code": "BITRIX_ERROR", "message": "Access denied", "b24Code": "0" } }

After

GET /v1/scrum/sprints/{sprintId}/stages and POST /v1/scrum/sprints/{sprintId}/stages answer a permission refusal with 403 BITRIX_ACCESS_DENIED — the code the common error reference already describes. It reads as "do not retry, grant the user access to the scrum project instead".

HTTP 403
{ "success": false, "error": { "code": "BITRIX_ACCESS_DENIED", "message": "Access denied" } }

Successful responses are unchanged: the column list still arrives with HTTP 200 and a created column with HTTP 201. The answer for a missing sprint is unchanged too — it stays 404 ENTITY_NOT_FOUND.

BC-0901-2: an empty employee photo is refused on update

Old format supported until: not provided

Before

On employee UPDATE, an empty or whitespace-only string in personalPhoto reached Bitrix24 as a command to remove the current photo. The single PATCH /v1/users/:id returned 200 success:true even though the photo was removed.

After

Such values are refused with INVALID_PARAMS before the Bitrix24 call. The single PATCH /v1/users/:id returns 400 success:false; batch routes keep their existing error envelopes. The global POST /v1/batch also refuses personalPhoto: null: its sub-call encoder turns null into an empty query-string value, the same remove-the-photo command. On PATCH /v1/users/:id and in the per-entity batch, null gets no new refusal. To leave the photo unchanged, omit personalPhoto. On CREATE in POST /v1/users, an empty string does not get the new refusal; the working inline pair and separate employee-invite validation are unchanged.

FIX-0901-3: rate limit descriptions now name the replica share, not just the total cap

Before

The descriptions of POST /v1/feedback in the GET /v1/guide directory, in the feedback.limits block of the GET /v1/me response and in the GET /v1/openapi.json schema named the limit as a number — "5 requests per minute". Requests are served by several backend replicas and each one holds its own share of the limit, so the client received less than promised and the X-RateLimit-Limit header disagreed with the description. The same mismatch was present on the help pages for submitting a ticket and uploading an attachment, and in the schema for five operations of the Cowork section.

After

The descriptions name the number and explain next to it that the cap is divided across the replicas, while the value actually in force arrives in the X-RateLimit-Limit header. For the Cowork operations in the schema, the 429 refusal description is aligned with the form already used on the help pages. A single shared 429 row on the feedback page is split in two — creating a ticket and uploading an attachment carry different counters.

Impact on integrators

The limit values did not change and the behaviour is the same as before. A client that relied on the number from the description was refused earlier than expected — the source of the value in force is now named explicitly: read X-RateLimit-Limit from the response.

BC-0901-4: task comment updates reject read-only fields

Old format supported until: not provided

Before

On a legacy card, PATCH /v1/tasks/:taskId/comments/:id could return HTTP 200 when a client sent a comment object from GET with an updated message, forwarding read-only fields to Bitrix24. An item in POST /v1/tasks/:taskId/comments/batch could similarly finish with success:true.

After

A single PATCH containing a read-only field returns HTTP 400 READONLY_FIELD before Bitrix24 is called. For a successful legacy-card comment update containing only {message}, the response remains HTTP 200; the existing 410 GONE remains unchanged on the new card.

In the custom batch, the top-level response remains HTTP 200 with success:true; the rejected item gets success:false and error:READONLY_FIELD, is not sent to Bitrix24, and does not stop valid sibling items.

What integrators should do

For a single PATCH, build a new body containing only {message}; do not send response fields such as id, taskId, authorId, createdAt, or their aliases back to the endpoint. In a custom batch item, keep lowercase id as the comment selector and send only message beside it; remove an additional ID and all other read-only fields. Clients that already send only documented writable fields need no changes.

FIX-0901-5: the 401 TOKEN_MISSING error now names the reason on every V1 route

Before

The reason a personal key had no Bitrix24 webhook was named only on entity routes (/v1/deals, /v1/tasks and so on) and in POST /v1/batch. Every other family — chats, lists, mail, scrum, notes, Open Channels, bots, userfields and the rest — answered with the flat text "API key has no tokens configured." and no error.details field. The same broken key got an explanation on /v1/deals and a text that implied nothing on /v1/chats.

After

The 401 TOKEN_MISSING body is built the same way on every V1 route: a personal key gets the reason in error.details.reason plus the text naming the required action, an app key gets a pointer to the missing OAuth step. The response remains HTTP 401 and the set of codes is unchanged.

Impact on integrators

Read error.details.reason — that is the contract, not error.message. The message text on these routes has changed, so code comparing it with the literal "API key has no tokens configured." stops matching; that parsing was unreliable before as well. The reasons are listed in the GET /v1/me response under b24Credentials.

FIX-0901-6: direct upload can be repeated after object deletion

Before

After a successful DELETE /v1/storage/objects/{key}, a new direct POST /v1/storage/objects/upload with the same key returned 409 STORAGE_KEY_DELETED until the object was physically purged 30 days later.

After

For an app object in the COMPLETED state without a multipart session, direct upload returns HTTP 200, preserves the same id and visibility, and writes new content. A deleted public link with that id becomes available again with the new bytes. This does not restore the previous content.

Path B remains disabled and returns 503 STORAGE_PRESIGNED_UPLOAD_DISABLED without a URL. Path C, deleted PENDING objects, and objects with a multipart session continue to return 409 STORAGE_KEY_DELETED. DELETE itself and subsequent reads without a new eligible direct upload continue to return 410 STORAGE_OBJECT_DELETED during the retention period.

Impact on integrations

No request changes are required. After deleting an eligible object, send the new bytes with a regular direct upload using the same key.

FIX-0901-7: a transient image-registry outage no longer marks a galaxy app broken

Before

POST /v1/infra/servers with a source field that hit 502 GALAXY_BASE_IMAGE_UNAVAILABLE — or ran the host out of disk — flipped the slot to status=error, even though the same refusal on POST /v1/infra/servers/:id/deploy left the status untouched and the error text promised the slot, its container and its /data volume were intact. Re-sending the deploy never cleared that error: GET kept reporting a broken slot, and the app stopped holding its host awake.

After

Both transient refusals leave the slot at status=provisioning; the cause stays readable in provisionError of GET /v1/infra/servers/:id. Re-sending the same deploy to a slot broken by such a cause clears error at the start of the attempt. An abandoned slot is still failed by the platform after ~20 minutes, but it keeps its real cause instead of the generic DEPLOY_INCOMPLETE. The error.hint copy, the /v1/me checklist and the docs no longer promise a "2–3 minutes" window: the registry outage can last an hour.

BC-0901-8: Regular chat-bot blocks key deletion

Old format supported until: not provided

Before

Deleting an API key could delete its linked regular chat-bot together with the token required for normal portal unregistration.

After

Deleting a key with a regular chat-bot, including a disabled Bot Platform row, returns 409 KEY_HAS_LINKED_AGENT. Take numeric bitrixBotId from details.bots in the 409 response, then unregister the bot through DELETE /v1/bots/:botId or transfer it to another key.

FIX-0901-9: file uploads and AI requests now answer 429 under memory pressure

Before

POST /v1/files/upload (up to 70 MB), POST /v1/note/documents/{id}/files (up to 40 MB), POST /v1/chat/completions (up to 30 MB) and POST /v1/audio/transcriptions (audio up to 25 MB) accepted any number of concurrent large bodies. Several parallel uploads at the ceiling could drop requests without a response — other requests in flight at that moment included.

One more observable difference: a request with a missing or invalid key on these routes could get 400 (unparsed JSON), 413 (size) or 415 (content type) — an answer about the body before the answer about the key.

After

Concurrent bodies over 1 MiB are bounded by their total size. A request over the bound gets 429 with code LARGE_BODY_BACKEND_BUSY and a Retry-After: 5 header, emitted before any Bitrix24 call, so it carries no side effects — and identically whether or not Content-Length is declared:

{
  "success": false,
  "error": {
    "code": "LARGE_BODY_BACKEND_BUSY",
    "message": "Too many large request bodies are being processed. Retry in a few seconds.",
    "retryAfter": 5
  }
}

On the OpenAI-compatible POST /v1/chat/completions, POST /v1/ai/chat/completions and POST /v1/audio/transcriptions (+ POST /v1/ai/audio/transcriptions) the envelope matches the rest of that surface — no success, lowercase code:

{
  "error": {
    "message": "Too many large request bodies are being processed. Retry in a few seconds.",
    "type": "rate_limit_exceeded",
    "code": "large_body_backend_busy",
    "retryAfter": 5
  }
}

A request with a missing or invalid key now gets 401 on all of these routes — the key is checked before the body is read. Successful requests and bodies under 1 MiB are unaffected; a retry after 5 seconds succeeds.

Important: on transcriptions the bound is counted from the declared Content-Length. An upload without one (Transfer-Encoding: chunked) is not counted against the shared total and is bounded only by its own 25 MB per-file ceiling.

FIX-0901-10: creating a Hermes agent no longer fails because of the startup payload size

Before

Creating a Hermes agent failed right after the server step. The virtual machine was never created, the agent stayed in the error state with an incident code, and the server field on the card stayed empty. Retrying produced the same result. The cause was the cloud startup payload growing past the size limit the cloud allows for such payloads.

After

Internal comments are no longer shipped to the cloud together with the install script, so the startup payload fits well within the limit again and the virtual machine is created. The install script itself and every other delivery path for it are unchanged. In addition, a size check now runs before the cloud is called: should the payload ever grow past the limit again, no cloud request is sent at all and Vibecode returns the usual provider error with an incident code.

NEW-0901-11: the business-process editor is available through the API

A new /v1/workflow-designer/* section works with templates of the new business-process editor in the editor's own language: blocks, connections, a catalog of block types, graph validation, drafts and publication. It is not the same as /v1/bizproc-templates, which reads and writes template rows with the graph as an opaque blob.

The bizprocdesigner scope is required — a separate one from bizproc. Add it to the key and re-issue the key.

Writing takes two steps. POST /v1/workflow-designer/templates/{id}/draft saves a draft: the running business process keeps executing its published version, so a draft can be shown to a person, rewritten or thrown away. POST /v1/workflow-designer/templates/{id}/publish makes the draft the working version — irreversibly, and it deletes every draft of the template, other people's included. Publication requires the draftFingerprint from GET /v1/workflow-designer/templates/{id}, so that exactly the graph you read and showed the person is the one published; a draft someone rewrote in the meantime is refused instead of quietly replacing it.

Start with GET /v1/workflow-designer/capabilities: it answers whether the editor is available to this portal and this key, and names the reason when it is not (DESIGNER_NOT_SUPPORTED — the portal is not updated to a version that serves the editor through the API, or the module is absent, DESIGNER_UNAVAILABLE — switched off or not in the plan, SCOPE_DENIED — the key lacks the scope, DESIGNER_REQUIRES_WRITE_KEY — the key is read-only and the operation writes, DESIGNER_PROBE_FAILED — the check did not complete and the editor state is unknown). These states cannot be told apart from a refusal of the methods themselves, which is why the check is a call of its own.

A read-only key is served by this section: the graph, the block catalog, the document fields, the portal instructions and validate all read. DESIGNER_REQUIRES_WRITE_KEY arrives only on the three writing operations — creating a template, saving a draft and publishing one.

Affected endpoints: GET /v1/workflow-designer/capabilities, POST /v1/workflow-designer/templates, GET /v1/workflow-designer/templates/{id}, GET /v1/workflow-designer/templates/{id}/brief, GET /v1/workflow-designer/templates/{id}/blocks, GET /v1/workflow-designer/templates/{id}/blocks/{blockId}, GET /v1/workflow-designer/templates/{id}/document-fields, POST /v1/workflow-designer/templates/{id}/validate, POST /v1/workflow-designer/templates/{id}/draft, POST /v1/workflow-designer/templates/{id}/publish

BC-0901-12: deleting a server now deletes the agent bound to it

Old format supported until: not provided

Before

DELETE /v1/infra/servers/:id deleted the server only. The agent that ran on it stayed alive on the Vibecode platform: its state still read as running, its bot stayed registered on the Bitrix24 portal, its key stayed valid, and the agent pointed at a server that no longer existed.

After

The agent bound to the server is deleted together with it. The agent row is marked deleted, the bot is removed from the Bitrix24 portal, the agent key is revoked, and the application card is removed from the Bitrix24 catalog. A successful delete still answers HTTP 200 with the body {"success": true}.

One new outcome appears. If another request was changing that same agent concurrently, the answer is 409 AGENT_DELETE_CONFLICT in the usual rejection shape {"success": false, "error": {"code": "...", "message": "..."}}. In that case the server is not deleted either: it keeps running and keeps being billed, and the request has to be repeated.

What integrators should do

An integration that expected the agent to survive a server delete and be reused has to be reworked: create the agent again after creating the new server. Treat AGENT_DELETE_CONFLICT as retryable — the server is intact, so repeat the same request. Deleting a server with no agent and deleting a server of kind GALAXY_APP behave as before.

2026-08-31

FIX-0831-1: a server whose agent never came up is no longer reported as running

Before

When the on-boot agent install aborted, the VM still reached running and the server stayed there. The server card and the server list returned status: "running" with provisionError and provisionErrorCode both empty — nothing in those responses told a working server from a broken one, and billing kept accruing.

{ "status": "running", "blackholeStatus": "NONE", "provisionError": null, "provisionErrorCode": null }

After

Such a server moves to error with an explanation and a new provisionErrorCode: "AGENT_NEVER_CONNECTED", and its billing is closed out.

{ "status": "error", "blackholeStatus": "NONE", "provisionError": "The server booted, but its agent never connected — …", "provisionErrorCode": "AGENT_NEVER_CONNECTED" }

Impact on integrators

Nothing to change: error is an existing status and no field was added. Worth knowing:

• A readiness wait now terminates — running with blackholeStatus: "NONE" no longer lasts forever. If you poll for running + CONNECTED, add an exit on error.
• Recovery is POST /v1/infra/servers/:id/repair, which reinstalls the agent over SSH. Recreate the server only if repair does not help.
• POST /v1/infra/servers/:id/start on such a server answers 422 with the code AGENT_NEVER_CONNECTED. The status did not change: this machine already got a 422 from /start (SERVER_WRONG_STATE, since it counted as running) — the code changes, not the status. Starting it fixes nothing and erases the explanation, which is why it is refused. A client that restarts failed servers on a schedule must read the code and call repair instead.
• Three lifecycle operations on such a server turn from a success into a refusal, because they require running: POST /v1/infra/servers/:id/stop and POST /v1/infra/servers/:id/reboot answer 422 with the code SERVER_WRONG_STATE, and POST /v1/infra/servers/:id/sleep-now answers 400 with NOT_RUNNING. Stopping such a machine is not needed either: billing is closed out with the verdict, so a scheduled stop saves nothing on it. The working actions are repair and DELETE /v1/infra/servers/:id — the same pair the response lists in availableActions.
• The verdict applies to newly created servers and never touches ones already running. The platform checks with the gateway first, so a live tunnel whose notification was lost is healed rather than failed. If the agent connects later, the server returns to running on its own and both fields are cleared.

FIX-0831-2: key issuance on a free plan now names the cause instead of "retry in a minute"

Before

When Bitrix24 refused REST because the portal's Bitrix24 plan does not permit it, key issuance and app installation answered 502 CONNECTOR_REST_UNAVAILABLE with the text "Bitrix24 did not issue the key. Retry in a minute". Retrying never helped: the plan gate does not clear on its own, and the response never said what did block the call.

After

The same situation answers 402 with a dedicated paywall code. The userMessage field states that a paid Bitrix24 plan is what unlocks the action. Successful responses are unchanged and still return HTTP 200, and every other refusal reason still answers 502 CONNECTOR_REST_UNAVAILABLE.

FIX-0831-3: search and research through the Linkup provider

Before

Every POST /v1/search or POST /v1/research call with provider: "linkup" was rejected by the provider: the platform did not send the required outputType field. For the same reason a Linkup key could not be connected — adding a BYOK key returned INVALID_CREDENTIAL with the text HTTP 400 even for a working key.

After

Linkup calls go through, and connecting a BYOK key reflects the real state of that key: a working key is stored, a non-working one is rejected.

In /v1/search the answer field is filled when include_answer: true and is null when include_answer: false; in that case the page text arrives in results[].content. The results[].published_date field is always null for Linkup — the provider returns no publication date, and the capability matrix in GET /v1/search/providers now reports that honestly.

FIX-0831-4: seamless dashboard sign-in from a signed Bitrix24 form

Before

Opening the dashboard from the Bitrix24 app catalog launched the platform address in a new tab. The user landed on the sign-in screen and then on the account picker, even though they had just clicked a button inside their own Bitrix24 account.

After

The licence-signed channel gained a second transition surface, cabinet. The Bitrix24-side module posts a signed form carrying BX_VIBE_SURFACE=cabinet to the new endpoint POST /microservice/open-cabinet (the trailing-slash variant is accepted too), and the user arrives in the dashboard already signed in, with no sign-in screen and no account picker.

Surface fields: BX_VIBE_AUD — the platform address the form is addressed to (mandatory, compared verbatim); BX_USER_EMAIL — the Bitrix24 user's email; BX_VIBE_NETWORK_STATE — the network-state hint, self-hosted only; BX_VIBE_TARGET — an optional relative path inside the dashboard, /dashboard by default. The signed field set and its order, the requirement on each field and the refusal codes are in the integration contract.

The session cookie is not set in response to a cross-site request: a successful response is a page on the platform domain with an auto-submitting form that exchanges a one-time code for the cookie same-site at POST /api/cabinet/handoff and forwards the user to the destination path. The code lives 120 seconds and is spent exactly once.

The issued session is an ordinary one but is bound to the Bitrix24 account it came from: switching the active account is refused, and the account listing serves only that one. Two-factor verification, terms consent, account access mode and blocks behave exactly as on an ordinary sign-in.

The surface sits behind a switch and is off by default: while it is off the endpoint answers 404. The app surface (POST /microservice/open-app) is unchanged.

FIX-0831-5: opening an application from the Bitrix24 catalog always acts as an account

Before

A Bitrix24 employee with no Vibecode account opened an application on the strength of the portal's signature alone: the platform issued a one-time init code carrying an empty Vibecode user id, and the application received an identity backed by no platform record at all. On a self-hosted portal such an employee opened as a guest, with the name and departments read out of Bitrix24; on cloud the platform asked the portal user.get before the redirect to confirm the employee was live.

After

Every open now has an account, and __init always carries a non-empty user. On cloud the account is created from the signed BX_NETWORK_USER_ID and BX_USER_EMAIL. On a self-hosted portal the employee confirms the identity themselves: the platform serves a server-rendered screen for the code mailed to the address from the signed form, and on a correct code the same request links the Bitrix24 member to the Bitrix24.Network profile and opens the application. The outbound user.get before the redirect is gone.

The e-mail code is now sent AND checked by Bitrix24.Network itself, through two trusted operations. The first takes the address: the Network finds or creates the profile behind it and mails the code as its ordinary e-mail confirmation. The second takes the same address plus the code and returns the profile for the confirmed address. The platform mails nothing and stores no code. Code lifetime and attempt count are the Network's; the platform keeps its own send-rate caps on top.

BX_USER_EMAIL moved out of the cabinet surface fields into the common part of the signed set: both platforms send it on both surfaces, right after BX_NETWORK_USER_ID (or after BITRIX_USER_ID when there is no network id) and before BX_VIBE_SURFACE. The field is optional — a form without it is served exactly as before, so an older module keeps working with no changes. The successful response is still a 302 to the application address carrying __init.

The account-creating branches sit behind a platform switch that is off by default: while it is off, an open with no account answers with a refusal page linking to the ordinary sign-in, and no partial profiles are left behind.

The "Authorize the application" page is reworked: one button instead of a button plus a quiet link, and once the application is authorized the page forwards to it by itself — no closing the tab and reopening the application from the catalog. The iframe therefore has to allow allow-popups. The e-mail confirmation screen opens no new tab: the code field unfolds behind a button on the same page, and a loader covers the card while the platform checks the code and connects the application. The address can no longer be changed there — only the one from the signed form is confirmed, and the single alternative is signing in on the platform yourself, through a link on that same screen. The full field set, the e-mail confirmation screens and the continuation endpoints are in the integration contract.

FIX-0831-6: Batch create of telephony lines returns the addressable number in results[].id

Before

POST /v1/telephony-lines/batch with action: "create" answered 200, but results[].id carried Bitrix24's internal numeric row id. It could not be used in PATCH or DELETE /v1/telephony-lines/:number — the line is looked up by number, so the request answered 422. The single POST /v1/telephony-lines already returned the correct number, so the two doors into the same create disagreed.

After

results[].id is the same number passed in that item's number field, and the same value the single POST /v1/telephony-lines returns. It comes back verbatim, including numbers with + and other characters. The response is still 200 and no other field changed.

FIX-0831-7: signing back into Cowork on a fee-free seat no longer fails

Before

Cancelling a fee-free Cowork subscription made every later desktop sign-in fail with 403 COWORK_SUB_CANCELLED: the cancelled seat was never revived, and a key is only issued for an active one. There was no way out from inside the app — this path has no browser route back to a fee-free seat — so the person stayed locked out for good.

After

A zero-price seat is revived at sign-in and the key is issued. A paid seat still answers 403 COWORK_SUB_CANCELLED / COWORK_SUB_PAUSED: resuming it is a payment, and that stays a deliberate action in the dashboard.

FIX-0831-8: `TOKEN_MISSING` for a personal key now names the webhook mint failure

Before

When a personal key (vibe_api_*) had no Bitrix24 webhook because the portal had refused the key owner the right to create incoming webhooks, or because the last mint attempt had failed, the 401 TOKEN_MISSING response still reported a generic reason (for example WEBHOOK_NOT_CONFIGURED) and pointed at GET /v1/me, without explaining that no webhook was coming or who needed to act.

After

In these two scenarios error.details.reason now returns WEBHOOK_MINT_REFUSED_BY_PORTAL (a portal administrator must act) or WEBHOOK_MINT_FAILED (the platform retries on its own), and error.message names the cause and the addressee explicitly. For WEBHOOK_MINT_REFUSED_BY_PORTAL the reconnect advice (POST /api/keys/:id/reconnect) is no longer included — the platform mints the webhook automatically once a portal administrator opens the right to create incoming webhooks, and retrying reconnect will not help. The response code, HTTP status and error shape are unchanged.

Impact on integrators

Handle WEBHOOK_MINT_REFUSED_BY_PORTAL and WEBHOOK_MINT_FAILED as distinct details.reason values alongside the already-documented ones — do not recreate the key or loop on reconnect for these reasons; wait for the portal administrator or the platform's automatic retry.

A separate note on the message text. error.message now branches on the reason and on whether reconnect is available for the key — and this affects more than the two new reasons. A key with no Bitrix24 scopes (VIBE_SCOPES_ONLY) gets its own wording, and keys the platform would refuse reconnect for (cowork keys, app keys, keys bound to a server or to a live agent) get advice to create a new key instead of advice to reconnect. The details.reason values in those scenarios are unchanged. If your code matches on error.message as a string, switch to details.reason: the message text is not a contract and does change.

FIX-0831-9: vibe top-up is open to self-hosted accounts on the international installation

Before

A self-hosted account on the international installation always got the BOX_TOPUP_NOT_AVAILABLE refusal. The subscription preview GET /v1/cowork/subscription/preview returned topUpAvailable: false for such an account, and the package catalogue came back empty.

After

A self-hosted account on the international installation tops up just like a cloud one — it gets the package catalogue, a payment link and topUpAvailable: true in the subscription preview. The BOX_TOPUP_NOT_AVAILABLE refusal remains only where top-up is closed to self-hosted accounts in the account's region. The response format is unchanged and the successful response remains HTTP 200.

2026-08-30

BC-0830-1: Presigned single-PUT upload is temporarily disabled

Old format supported until: not provided

Before

Path B minted a presigned PUT URL for single-PUT uploads and published it through /complete.

After

Path B (URL creation and completion) now fails closed with 503 STORAGE_PRESIGNED_UPLOAD_DISABLED. Use direct upload (Path A) or multipart upload (Path C) for new writes; legacy PENDING reservations are neither published nor automatically released by GC.

BC-0830-2: an application rename no longer reports success without confirmation from Bitrix24

Old format supported until: not provided

Before

On a developer-key rename PATCH /v1/apps/{id} removed the previous menu-item binding and created a new one. When Bitrix24 rejected the new binding after a confirmed removal, the response was 502 BITRIX_PARTIAL_REBIND and the item stayed removed.

On the cloud OAuth path the same method behaved differently in another case: when Bitrix24 confirmed neither the removal of the previous binding nor the new one, the response was 200 OK with a warning and the new name was saved. The menu item either disappeared from the account or kept its previous label, and a repeated request no longer rebound it, because the platform considered the name current.

After

On a developer-key rename the platform makes one attempt to restore the previous label. Successfully restored placements are listed in the new error.restored field and need no manual repair. The error.unbound field lists the placements to check on the account: those left removed, plus those whose removal Bitrix24 never confirmed. The new error.bitrixCodes and error.bitrixStatuses fields carry sanitised diagnostics for every rejected call.

The cloud OAuth path now answers 502 BITRIX_PARTIAL_REBIND and does NOT save the new name when Bitrix24 confirmed neither the removal nor the new binding.

What integrators should do

Treat 502 BITRIX_PARTIAL_REBIND as "the name was not saved" and repeat the request — a retry fires the rebind again. The former 200 OK did not mean success in this scenario. Only the placements in error.unbound need manual restoration through POST /v1/placements/bind.

FIX-0830-3: for `bitrix/*` models a stream that never started also ends with a retryable error

Before

When the upstream of a bitrix/* model sent no response headers, the platform silently repeated the request and waited for another full budget. The client received nothing meanwhile — up to two full budgets of silence — and then saw a generic provider failure that does not tell a stalled stream setup apart from any other unclassified error.

data: { "error": { "code": "ai_provider_unavailable", "type": "server_error", "retryable": true, "retryAfter": 6 } }
data: [DONE]

After

Stream setup for these models makes a single attempt on one shared budget. If the headers do not arrive within it, the wait no longer doubles and the stream ends with the same stream_idle_timeout event as a stream that went silent mid-response — naming the stream itself as the thing that stalled.

data: { "error": { "code": "stream_idle_timeout", "type": "server_error", "retryable": true, "retryAfter": 7 } }
data: [DONE]

The wait no longer doubles invisibly and the reason is named precisely. Models from other providers are not affected yet: their stream setup still takes two attempts and ends with the generic ai_provider_unavailable.

2026-08-29

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 the portal 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. Portal queue overflow, queue wait timeout and portal 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 portal's response could previously end up in it. The code and the status are unchanged.

2026-08-28

FIX-0828-1: stopping a server is no longer billed as a full running hour

Before

After a server was stopped via POST /v1/infra/servers/{id}/stop, the transition to sleep was not recorded in the status journal. When the hourly charge for that hour ran late, it relied on the last known record — running — and billed a full hour at the running rate, including the time the machine was already stopped. The endpoint response itself was correct; the discrepancy showed up only on the invoice.

After

The transition is recorded immediately, and the hour is billed as it actually happened: running time up to the stop, sleeping time after it. The response shape and status codes are unchanged, and the HTTP 200 response is preserved.

FIX-0828-2: a late upload through a valid URL preserves the object

Before

If an upload through a signed URL started more than one hour after issuance, its reservation could be deleted before the URL expired. A later completion returned 404, while the uploaded bytes remained without an API object.

After

An empty reservation remains until the maximum signed URL lifetime expires. The successful completion response remains unchanged; a late upload through a still-valid URL remains linked to its API object.

FIX-0828-3: GET /v1/guide returns the paging rules as a single paginationCanon block

Before

The paging and record-counting rules were repeated inside every entity of the response. The operations.search.paginationStability fields and the operations.search.params.withTotal description carried the same text for every entity.

After

The same text arrives once, as a top-level paginationCanon block. The wording is carried over verbatim — no rule was rewritten or shortened. The same-named fields inside the entities are still present and carry a pointer to the matching paginationCanon entry.

The one exception is operations.search.paginationStability.counting. It still arrives per entity with its own text, because how to obtain an exact count depends on whether that entity offers the aggregate operation.

Impact on integrators

Calls work exactly as before and no response field was removed. If your code read the rule text out of the entity fields, read it from the paginationCanon block instead. On a full set of scopes the response is roughly 37 percent smaller.

FIX-0828-4: task comment filter and sort accept camelCase field names

Before

GET /v1/tasks/:taskId/comments accepted only raw Bitrix24 field names in filter and sort. The names authorId and createdAt, in which the same fields arrive in the response, returned 400 UNKNOWN_FILTER_FIELD or 400 INVALID_SORT_FIELD.

After

The filter and sort parameters accept camelCase names alongside raw ones: id, authorId, authorName, createdAt, and sort additionally accepts authorEmail. Card-type limits are unchanged: filtering by authorName and sorting by authorName or authorEmail are still accepted only on the old card and return 400 on the new one. When filter names one field twice in different spellings of the name or of the equality sign, the response is 400 INVALID_FILTER. Unknown names still return 400.

Impact on integrators

Filtering and sorting can use authorId and createdAt — the same names in which these fields arrive in the response. Existing requests with raw field names require no changes.

BC-0828-5: Deploy outcomes can be confirmed after a dropped connection

Old format supported until: not provided

Before

If the gateway connection dropped during a deploy, the client received neither the outcome nor the operation identifier. A repeated deploy could encounter EXEC_BUSY without answering the main question: whether the first deploy completed.

After

POST /v1/infra/servers/:id/deploy stores an observable standalone or galaxy deploy outcome, while GET /v1/infra/servers/:id/operations returns recent operations started by the current API key even when the terminal response carrying operationId was lost. For GATEWAY_UNREACHABLE, GATEWAY_CONNECTION_TERMINATED, GATEWAY_STREAM_ERROR*, GATEWAY_TIMEOUT*, TUNNEL_NOT_FOUND, and a post-drop Galaxy interruption, the outcome is stored as unknown, and error.hint requires reconciling the operation, server, and logs first. On standalone this applies equally when the transport throws and when the gateway reports a timeout/error frame in-band during exec or upload/download; that unconfirmed outcome carries error.retryable: false and does not trigger an internal retry. After confirmed EXEC_BUSY, a standalone server may use /unstick only when no operation is still running; tenant recovery is unsupported for a shared Galaxy host, so wait and contact support if the refusal persists.

What integrators should do

When error.retryable: false, do not resend the same deploy: read GET /v1/infra/servers/:id/operations, the server state, and logs first. Retry only after a durable failed outcome when the response hint explicitly permits the same request. Do not delete or recreate the slot while the outcome is unknown.

FIX-0828-6: task comment creation returns the correct numeric ID

Before

On the new task card, POST /v1/tasks/:taskId/comments and POST /v1/tasks/:taskId/comments/batch with action: create could return id: null for a found message when its numeric identifiers arrived as strings. With multiple matches, string comparison could select the wrong ID.

After

Both endpoints return the found message's numeric id and compare matching IDs as numbers. The single POST response remains HTTP 201. The batch response remains HTTP 200, and a successfully created item remains success: true.

If the search does not find the message or cannot identify it unambiguously, id: null remains a valid successful result: the comment has already been created, and retrying the request may create a duplicate.

Impact on integrators

No client changes are required. Continue supporting number | null and do not treat null as a failed creation.

BC-0828-7: incomplete public uploads are no longer anonymously accessible

Old format supported until: not provided

Before

For a PUBLIC object in the PENDING state, GET /v1/public-storage/{portalId}/{objectId} returned 302, while HEAD /v1/public-storage/{portalId}/{objectId} returned 200. The file became accessible without authentication before the upload was completed.

After

Both requests return 404 while the upload remains in the PENDING state. Anonymous access is available only for a PUBLIC object whose upload is complete.

What integrators should do

After uploading the file, call POST /v1/storage/objects/complete and publish the anonymous link only after a successful response.

FIX-0828-8: MCP returns the Drive file content instead of a network error

Before

The download action of manage_file parsed the GET /v1/files/:fileId/download response as service JSON, although that request returns file bytes. On any real file the agent got success: false with code NETWORK_ERROR and an Unexpected token … message — the first bytes of the already downloaded file presented as a connection failure. The action had no working answer at all.

After

The action returns content with the file content in base64, plus contentType, size and filename — mirroring how upload accepts content. Files above 10 MiB are refused with code FILE_TOO_LARGE, and the message names the way to get such a file: a request to the same address with the same API key. Error responses stay the usual platform envelope: a missing file is ENTITY_NOT_FOUND, not NETWORK_ERROR. The generic call_api, which only reads JSON envelopes, now refuses known non-JSON routes up front with NON_JSON_RESPONSE_UNSUPPORTED instead of making a request it cannot parse. It refuses the browser entry points of the OAuth and connect flows the same way, with REDIRECT_ROUTE_UNSUPPORTED: they answer with a redirect, and the request used to travel there with the API key and then follow that redirect to an address the platform does not choose. The path is reduced to its canonical form before the check, so spelling it with .. no longer slips past the refusal, and a full address in place of a path is refused with INVALID_PATH. The download action now requires the file id to be a positive whole number: a fractional value used to return another file's content as a successful answer. The REST request itself still returns binary data, so ordinary clients work as before.

FIX-0828-9: concurrent direct uploads of one object are coordinated

Before

Concurrent POST /v1/storage/objects/upload calls for the same physical app address could mix file content and its metadata.

After

Path A direct uploads with an app-bound key run one at a time. After a turn is acquired, the response remains HTTP 200. If safe write ownership is not confirmed within 60 seconds or the concurrency limit, the request receives 409 STORAGE_KEY_CONFLICT before writing to object storage. Retry the entire request.

The guarantee applies only to Path A with an app-bound key. It does not extend the behaviour of personal keys (appId = null) or Paths B/C.

Impact on integrators

The successful response format is unchanged. On STORAGE_KEY_CONFLICT, retry the original request in full.

FIX-0828-10: create and update response specifications reflect the identifier

Before

The OpenAPI specification and response examples for create and update operations promised a full entity where the API returns only data.id.

After

OpenAPI and the documentation describe the actual response with data.id. The HTTP 201 status for create, the HTTP 200 status for update, and API runtime behavior are unchanged.

Affected endpoints: POST /v1/bizproc-activities, PATCH /v1/bizproc-activities/:code, POST /v1/bizproc-robots, PATCH /v1/bizproc-robots/:code, POST /v1/bizproc-templates, PATCH /v1/bizproc-templates/:id, POST /v1/calendar-sections, PATCH /v1/calendar-sections/:id, POST /v1/telephony-lines, PATCH /v1/telephony-lines/:number.

Impact on integrations

Existing requests require no changes. Regenerated clients now see the actual successful response shape.

FIX-0828-11: commands in a galaxy app are no longer refused before dispatch

Before

POST /v1/infra/servers/{id}/exec on a galaxy app answered 502 with code EXEC_FAILED and a message about safe container execution not being supported. The refusal hit every app and depended neither on the command nor on the state of the container: the request never reached the container at all.

After

The command runs in the app container, and the successful response remains HTTP 200 with the exitCode, stdout, stderr and duration fields — the same shape as on other servers. The CONTAINER_NOT_READY code for a stopped or missing container is returned where the platform can confirm that state; where it cannot, the reason arrives in the stderr of the result and the response itself is still HTTP 200.

FIX-0828-12: Node.js 20 runtime templates install more reliably

Node.js 20 in node20* templates is now installed more reliably when external network access is unavailable.

Before

The template performed an unbounded NodeSource installation. On a network failure, Node.js 18 could be installed, and the deploy then failed only with a generic version-check error.

After

The NodeSource installation uses bounded network attempts and an integrity check. If it fails, its package source is temporarily isolated, pre-existing configuration is preserved, and a verified Node.js 20 archive is used as a fallback; runtime identifiers and the deploy API stay unchanged.

FIX-0828-13: A ZIP deploy no longer asks you to change the archive format when the server is busy with another command

Before

While another command was running on the server, POST /v1/infra/servers/:id/upload with a zip and extract: true, and a galaxy-app deploy from a zip, reported a failed unzip install (UNZIP_PREFLIGHT_FAILED / a build failure) and advised re-packing the archive as .tar.gz.

After

A short-lived busy command channel is retried by the server. If the channel is still busy, the response is 409 with code EXEC_BUSY (on a galaxy-app deploy — GALAXY_APP_BUSY), retryable: true, and a Retry-After header. Do not change the archive format. A real failure to install unzip is still 502 UNZIP_PREFLIGHT_FAILED and the .tar.gz advice.

Impact on integrators

Retry using Retry-After. Do not re-pack the archive because of EXEC_BUSY / GALAXY_APP_BUSY. The UNZIP_PREFLIGHT_FAILED branch is unchanged.

FIX-0828-14: a payment with an inflated vibe count is held instead of rejected

Before

A payment.paid event whose metadata.tokens was ABOVE the catalog count received HTTP 400 with code TOKENS_MISMATCH. The rejection was terminal: no retry follows for that event, while the payer has already been charged — the credit never happened and the payment surfaced in no review queue.

After

Such an event is accepted as held: HTTP 200 with body { "ok": true, "held": true, "reason": "TOKENS_ABOVE_CATALOG", "vendor_reason": "catalog-drift-over" }. No Vibe credits are added — the payment enters the review queue, the same way the opposite-direction TOKENS_BELOW_CATALOG hold does. The TOKENS_ABOVE_CATALOG value of reason is new; the two directions carry separate dictionary names because an overpayment and an underpayment owe different amounts.

The downward direction (TOKENS_BELOW_CATALOG) is unchanged. An unreadable count is still rejected with BAD_TOKENS.

FIX-0828-15: a pending-deletion owner's key no longer calls Bitrix24 methods through V1

Before

A portal owner's key with scheduled self-deletion could still call some Bitrix24 methods through V1. The restriction did not cover every generated and handwritten wrapper, REST 3.0 method, direct call, and batch request.

After

All V1 methods that use a portal-bound APP/OAuth key to send requests to Bitrix24 return 503 user_self_deletion_pending with Retry-After before dispatch. This includes GET /v1/lists, GET /v1/calendar/settings, GET /v1/chats/recent, GET /v1/workday/status, GET /v1/applications, POST /v1/apps, tariff-refresh and trial-activation methods, and POST /v1/batch.

For a pending-deletion owner's READONLY key, this 503 takes precedence over WRITE_BLOCKED_READONLY_KEY. A fully authenticated active owner's key still receives the READONLY rejection, while earlier authentication and account-state errors keep their existing codes.

V1 metadata methods, including plain GET /v1/me without refresh=tariff, the MANAGEMENT control plane, and methods that operate only on Vibecode platform data are not frozen by this change.

Impact on integrators

No integration changes are required. On a 503 response, retry no earlier than the Retry-After value.

BC-0828-16: include now requires the scope of the related entity

Old format supported until: not provided

Before

The include parameter did not check whether the key held the scope of the entity it pulled in. Only the entity you were reading was checked. A key holding just tasks could therefore read a full employee record through GET /v1/tasks/{id}?include=responsible, while the same key was refused on /v1/users.

After

Both sides of the relation are checked. When the scope of the related entity is missing, the request is refused with code SCOPE_DENIED and HTTP 403, and the message names the missing scope and the relation that needed it.

This affects relations whose two sides require different scopes: responsible and creator on tasks and owner on workgroups require user, while catalog on product sections requires catalog. Relations that stay within one scope — preset on requisites or parentSection on product sections, for example — are unchanged.

If your integration uses such a relation, add the missing scope to the key: the scope set is editable on the key itself, there is no need to reissue it.

Affected endpoints: every endpoint that accepts include — read by identifier, list reads and POST /search. The mechanism itself — including related records.

NEW-0828-17: include for requisites, workgroups and product sections

Three reference entities got their relations, so the include parameter is now declared and works on them. Requisites gained preset, the requisite preset that defines the field set. Workgroups gained owner, the record of the employee who owns the group. Product sections gained two at once: catalog, the trade catalog the section belongs to, and parentSection, the parent section, which comes back empty for a top-level section.

The related record still arrives in the _included field next to the record itself, on list reads, on read by identifier and in the POST /search body. The mechanism limits are unchanged: at most three relations per request, and on a selection of more than 200 records relations are not resolved and the answer is marked includeSkipped.

The other reference entities still do not declare include, and that is a decision rather than an omission. Bitrix24 returns deal pipeline stages as a string code instead of a reference-record identifier, so there is nothing to join them by. On a reference record the pipeline number is meaningful only together with the CRM object type, and one and the same number belongs to a deal pipeline and to a smart-process pipeline at the same time. On a document template the file identifier is not addressable through Drive methods, and the numerator is not exposed as a separate entity in the API. The workgroup member list is served by its own endpoint rather than through include.

Affected endpoints: GET /v1/requisites, GET /v1/workgroups, GET /v1/product-sections, their read by identifier and POST /search. The mechanism itself — including related records.

FIX-0828-18: select combined with include no longer empties the relation on list and search

Before

When a list request or POST /search carried both select and include and the foreign key was not named in select, the related record came back empty. GET /v1/deals?select=id,title&include=company returned an empty _included.company, even though the same relation resolved without select. Read by identifier was unaffected.

After

The relation is resolved before the answer is narrowed to the requested fields, and the foreign key is added to the internal request on its own. The public answer is not widened by it: it still carries only the fields you named, plus the _included block.

Affected endpoints: list reads and POST /search on any entity that declares relations. The mechanism itself — including related records.

NEW-0828-19: the current-user profile is now in the specification and the reference

The method GET /v1/users/me already worked, but it was not declared in GET /v1/openapi.json, so it reached neither the API reference nor the endpoint map. A client checking against the specification did not find the method and concluded it did not exist.

The operation is now described: scope user, the same response shape as GET /v1/users/:id plus a tri-state isAdmin field. The behaviour of the method itself is unchanged.

isAdmin is null when the check could not be completed. The profile is still returned in full, so gate on isAdmin === true rather than on a negation.

FIX-0828-20: `topUpAvailable` for a self-hosted account reflects the self-hosted checkout

Before

GET /v1/cowork/subscription/preview answered topUpAvailable: true for a self-hosted account whenever sales were open in its region at all. Self-hosted accounts buy through a separate checkout that opens separately, so the flag could promise a top-up that the very next order request refused.

After

The flag is computed from the availability of the self-hosted checkout in the account's region. The HTTP 200 response is unchanged and carries the same fields; for cloud accounts the value did not change. While the self-hosted checkout is closed, the answer is topUpAvailable: false with currency: null, and an attempt to start a top-up answers with code BOX_TOPUP_NOT_AVAILABLE.

FIX-0828-21: the auth key now gets the scopes the portal actually grants

Before

When an application's personal API key carried no Bitrix24 scopes, the platform had no credential to ask the portal with, and the auth key was issued with crm + placement only. An app that needed tasks, chat or disk hit silent permission errors, and an issued key cannot be widened — only re-issued.

After

Scopes are probed over the channel the platform manages the portal with, so the set no longer depends on whether a particular application key has a webhook. The auth key receives the intersection of the portal's available scopes with the supported ones, as designed. When there is nothing to ask with, behaviour is unchanged and issuance is not blocked.

FIX-0828-22: an employee photo can be written through the API again

Before The personalPhoto field is declared a string, so any array or object in it was refused with 400 INVALID_PARAMS — and the [file name, base64] array is the only shape Bitrix24 accepts. On the entity routes no shape could write the photo: a base64 string and a URL answered 422, batch routes 400. It only travelled through the POST /v1/users/invite wrapper.

After On write, personalPhoto takes the file inline: an array of exactly two non-empty strings — the file name and its base64 content — on POST /v1/users and PATCH /v1/users/:id. Reading the field is unchanged, it still returns the photo URL. Other shapes stay refused on purpose: the nested {"personalPhoto": {"fileData": [...]}} is accepted by the portal with success yet clears the photo. Batch routes refuse the photo: a batch sub-call travels as a query string under the global body cap, and past its length limit the value would be truncated while still answering success. The POST /v1/users/invite wrapper accepts the same shape — it translates the field name and validates the pair separately — but its body limit is still the global one (1 MiB against the 40 MiB of the single routes), so send a real photo through POST /v1/users or PATCH /v1/users/:id.

2026-08-27

NEW-0827-1: aggregation marks a partial total next to the number itself

Before

POST /v1/{entity}/aggregate with sum / avg / min / max computes over the first 5000 records matching the filter. The incompleteness marker lived in data.meta.truncated alone, while data.aggregates.amount looked like { "sum": 1234567 } — a plain number with nothing attached. A client reading only the total received an understated result under code 200 with nothing to branch on: data.count meanwhile reported the full number of records.

After

When the selection is truncated, every field object in data.aggregates and in groups[].aggregates additionally carries truncated: true — { "sum": 1234567, "truncated": true }. The same condition adds a warning with code AGGREGATE_TRUNCATED to data.meta.warnings. The sum / avg / min / max values stay numbers, nothing wraps them into an object. On a complete selection the response does not change at all: the field object carries no truncated key and no meta.warnings appears. The 5000 ceiling and data.count behave as before.

Grouping gains one more field — groups[].truncated: on a truncated answer the group object itself carries this marker next to its counter. The marker says the answer is a sample; whether the group counter is exact is shown by meta.aggregatePath — on the ordinary walk groups[].count is computed over the slice that was read, while under the stage-count mode (meta.aggregatePath: "fanout") it comes from a separate probe and is exact. On a count-only grouping it is the only marker next to a number: a count expression produces no field object, and both aggregates bags come back empty. data.count and data.meta.totalRecords stay exact at any size and never carry it.

Alongside the incompleteness marker the response now always reports the size of the gap. Previously meta.recordsShortfall arrived only when the truncation was NOT caused by the ceiling: on a selection above 5000 records the response raised truncated: true with no gap-size field at all. That case is the most common one: on a pipeline of 20,000 deals a client saw "this answer is a sample" and zero as the size of what was missing. Now every reason for truncation carries a quantifier next to the marker — meta.recordsShortfall (how many records never reached the numbers) or meta.pageErrorSample (when the slice was cut short by a sub-page error). On a complete selection neither key appears in the response, as before.

A false alarm is removed at the same time. The truncation marker used to be raised from the comparison "more than 5000 records in total", which is only an indirect sign that the read will be cut. On entities where the limit never reaches Bitrix24 — pages and sites (landing.*), Open Channels configs — nothing is cut and every row is read. Such a response still declared itself a sample. The marker is now raised from the fact: fewer rows read than promised, then and only then. A fully read selection of any size counts as complete again.

This also closes a gap in grouping deals by stage: when a stage walk returned fewer records than its probe had counted (usually because of access rights), the response used to arrive with data.meta.truncated: false and looked complete. Such a response now raises truncated honestly — and with it comes both the marker next to the number and the warning.

BC-0827-2: runtime installation order and nginx startup have changed

Old format supported until: not provided

Before

During a redeploy, the runtime was installed after the previous app version had been stopped. A failed installation could leave the app stopped. For static, php83, and php83-mysql, package installation could implicitly start and enable the system nginx.service, and a request could rely on that process.

After

POST /v1/infra/servers/:id/deploy installs the runtime before stopping the app and replacing its files. If installation fails, the previous app is not stopped. Installing nginx for static, php83, and php83-mysql does not start the system nginx.service or leave it newly enabled. The existing service enablement state is preserved.

What integrators should do

For static, php83, and php83-mysql, make sure the command in the start field starts the process that listens on the application port inside app.service. Do not rely on an implicit start of the system nginx.service. Requests using other runtimes do not need to change.

NEW-0827-3: unfinished BOX account reason and employee identity transfer between accounts

The BOX account card with an unfinished connection (accessPending: true) in the GET /api/portals response now carries a reason in the optional accessPendingReason field: transfer_requested — the employee already has a pending request to move their link to this Bitrix24 account from another Vibecode account, incomplete — the connection is simply unfinished. Such requests are managed by the new /api/box-transfers/* routes: the current holder lists their pending requests, opens one via the email link, and approves or declines the transfer.

FIX-0827-4: unfinished BOX account connection is visible in the list

Before

GET /api/portals silently hid a BOX account whose connection was unfinished.

After

The account card is returned with the new accessPending: true field.

FIX-0827-5: user invitations preserve all profile fields

Before

POST /v1/users/invite accepted ten writable profile fields in the regular Vibecode API format but forwarded them without converting their names. The user was created while the photo, external ID, time zone, and personal details remained empty.

After

POST /v1/users/invite converts these fields to the Bitrix24 format. Clients do not need to change their requests, and the previous Bitrix24 field format keeps working.

FIX-0827-6: single comment lookup finds a comment with a string identifier

Before

GET /v1/tasks/:taskId/comments/:id could return 404 NOT_FOUND when Bitrix24 returned the found message identifier as a string. The same comment was still present in the task comment list.

After

The endpoint normalizes the numeric identifier from the Bitrix24 response and returns the found comment with numeric id and authorId values.

Impact on integrations

No client changes are required.

FIX-0827-7: contact select accepts typed email addresses again

Before

POST /v1/contacts/search and a contact sub-call in POST /v1/batch rejected emailWork, emailHome, and emailMailing with UNKNOWN_SELECT_FIELD, even though contact responses already contained these values. GET /v1/contacts/fields did not list these names.

After

Both operations accept the three names in select and return a successful response with the selected values. GET /v1/contacts/fields describes them as nullable read-only fields.

FIX-0827-8: tariff headers are returned for infrastructure requests

Before

Responses from the /v1/infra/* endpoint family did not contain X-Tariff-Checked-At or X-Tariff-Is-Commercial, even when the tariff check had completed successfully.

After

Responses from /v1/infra/* contain tariff headers under the same rules as /v1/me: the time of the last successful check and the commercial-tariff indicator are returned when the corresponding portal data is available. The response status and body are unchanged.

Impact on integrators

No request changes are needed. A missing header once again means that the corresponding tariff-check data is unavailable, rather than that the infrastructure route was skipped.

NEW-0827-9: array element schemas are available in field contracts

GET /v1/orders/fields, GET /v1/basket-items/fields, and GET /v1/guide now return itemSchema for arrays with a declared element shape. The schema recursively describes type, readonly, nullable, properties, and nested itemSchema values. Clients can optionally read the new field, and existing integrations continue to work without changes. The separate items key continues to contain the raw Bitrix24 value directory for enumeration fields.

FIX-0827-10: lists without a total no longer look complete too early

Before

If Bitrix24 did not return the total record count, a list request with a limit above 50 stopped after the first page. A full window of up to 50 records could also look like the last page because its size was treated as the collection size.

After

The platform continues reading after each full page and stops at a short page or the request limit. When the collection end is not yet proven, the total remains unknown and meta.hasMore or truncated reports that more records may exist.

Impact on integrations

No request changes are required. Requested windows larger than one page are no longer silently truncated; GET /v1/mail/messages now always includes a boolean truncated signal and omits an unknown total instead of returning null.

Affected endpoints: GET /v1/humanresources/nodes, GET /v1/mail/mailboxes, GET /v1/mail/messages.

NEW-0827-11: the self-description now points at the Cowork/Code promo code docs

The GET /v1/guide and GET /v1/me responses now name the desktop application's promo code pair. The cowork section of guide.ts carries the new docs.couponPreview and docs.couponRedeem pointers to the POST /v1/cowork/coupon/preview and POST /v1/cowork/coupon/redeem pages, and the /v1/me rules gained an item about them: which key class is required, how the check differs from the redemption, and why accessGranted: false deserves a screen of its own.

The endpoints themselves behave as before — what is new is that an integrator or an agent finds their description without reading the changelog.

FIX-0827-12: the Cowork/Code rate limits no longer quote a number the client never receives

Before

The GET /v1/guide reference, the GET /v1/me rules and the Cowork/Code documentation pages quoted rate limits as a concrete number: 20 requests per minute for POST /v1/cowork/coupon/preview, 10 for POST /v1/cowork/coupon/redeem, 30 for GET /v1/cowork/subscription/preview, 5 for DELETE /v1/cowork/key, 3 per five minutes for POST /v1/cowork/deploy-key, 30 for GET /v1/cowork/applications/defaults and 6 for POST /v1/cowork/applications. None of those numbers ever reached the client: the cap is divided across the platform's processes, and the x-ratelimit-limit header returned 7, 4, 10, 2, 1, 10 and 2 respectively. For deploy-key, key and the create-application wizard the two channels of one endpoint contradicted each other — the page promised one thing while the header returned another.

After

The GET /v1/guide reference, the GET /v1/me rules and the section's documentation pages now name the x-ratelimit-limit response header as the source of the current value and ask you not to hard-code a number in client code. The endpoints themselves did not change and the response is unchanged — what was corrected is the description that diverged from it. A client that already read the header changes nothing.

What this entry does NOT cover. The machine schema GET /v1/openapi.json still quotes numbers for five operations of the section — subscription/preview, deploy-key, applications/defaults, applications and key — and those numbers diverge from the header exactly as the others did. A client generated from the schema must still read x-ratelimit-limit rather than the value in the operation description. One promise in the schema is accurate: the "three requests per hour" on POST /v1/cowork/activate-market-trial, where the cap is multiplied by the process count before the division.

FIX-0827-13: telephony line creation returns a usable key

Before

POST /v1/telephony-lines returned an internal numeric identifier. It could not be used in the path for updating or deleting the created line.

After

The data.id field contains the created line number. This value can be used in subsequent update and delete requests.

Impact on integrations

No action is required. New create responses immediately contain an addressable key.

NEW-0827-14: time entry lists explicitly reject unsupported filter envelopes

Before

An unsupported filter in GET /v1/task-time and GET /v1/tasks/:taskId/time could return status 200 with a broader result set than the client expected.

After

A non-empty, bracket, JSON, or repeated filter returns 400 UNSUPPORTED_FILTER. For requests with the named userId, taskId, from, and to parameters, the response remains HTTP 200 and their behavior is unchanged.

FIX-0827-15: PUBLIC app robots.txt is available to crawlers

Before

Exact GET and HEAD requests to /robots.txt always received the gateway's local denial, even when the app had accessPolicy=PUBLIC, was running, and served its own file.

After

With accessPolicy=PUBLIC and a live tunnel, exact GET and HEAD requests to /robots.txt return the app response: 200 text/plain with a complete non-empty GET body no larger than 1 MiB (HEAD has no body), or 304. For every other policy, an unavailable app, or any invalid response, the gateway still returns local 200 text/plain with Disallow: /.

Impact on integrators

A PUBLIC app can now control indexing through its own /robots.txt file. No change is needed for non-public apps: denial remains fail-closed by default.

FIX-0827-16: entity filters are no longer lost on list calls

Before

list_entities could send filters as ordinary query parameters. This made a field named sort collide with the sorting directive, while openline-configs could return the full list instead of a filtered result. On envelope-based entities, a filter could also be lost in GET /v1/{entity}/aggregate, POST /v1/batch, and POST /v1/{entity}/batch.

After

list_entities sends fields through filter[...], separately from sorting. Every V1 list path applies the envelope declared by the entity, so a non-empty filter reaches Bitrix24 and a non-matching filter returns an empty result instead of the full collection. The custom bookings list accepts the same bracket form for its required dateFrom/dateTo window while preserving the existing flat form.

Impact on integrations

No request changes are required. Previously over-broad successful responses now match the supplied filter.

FIX-0827-17: the application access list contains portal employees only

Before

GET /v1/infra/servers/{id}/access returned every audience row in users[]. The element's id field is declared required, yet a grant issued to someone outside the server's portal has no portal number at all — such an element would arrive with an empty id, breaking any client that reads the field as required.

After

users[] contains only rows carrying a portal number. Rows addressed by a network identifier are excluded from this list — they live in a different identifier space, and the two must never be mixed. On today's data the response is unchanged: no such rows exist yet. The same rule applies to the matching dashboard screen.

FIX-0827-18: the `connect` step of repair status no longer fails for an agent that did connect

Before

Server repair counted the connect step as complete only when the version of the agent that came up matched the version set in platform settings. If the agent connected on a different version, the tunnel was up and blackholeStatus read CONNECTED, yet GET /v1/infra/servers/{id}/repair-status returned status: failed, step: connect and error: "Agent did not connect".

After

The connect step completes once the agent connects to the Gateway — exactly as the step order is described on the operation page. The installed agent version is still returned in data.agentVersion and no longer affects the repair outcome.

2026-08-26

FIX-0826-1: socnetGroupId now works on the nested resources of workgroup lists

Before

The socnetGroupId parameter was honoured only on the lists themselves — GET /v1/lists and GET /v1/lists/{iblockId}. The nested resources accepted it and dropped it silently: GET /v1/lists/{iblockId}/elements, fields, sections, property files and every delete reached Bitrix24 without the workgroup id when iblockTypeId=lists_socnet. Bitrix24 looked the infoblock up outside the workgroup, failed to find it and answered with a wrong-infoblock-type error, so the client saw a 422 even though it had supplied the group.

After

socnetGroupId reaches Bitrix24 from every endpoint of the /v1/lists family: in the query string on reads and deletes, in the request body on creates and updates. The elements, fields and sections of a workgroup list come back exactly as they do for an ordinary list.

Impact on integrators

No request changes are needed. If a workgroup-list traversal was built on direct lists.* calls because of this defect, it can now be assembled from the platform endpoints.

BC-0826-2: exec into a Galaxy app answers CONTAINER_NOT_READY instead of a false success

Old format supported until: not provided

Before

POST /v1/infra/servers/{id}/exec on a Galaxy app whose container was not up yet answered 200 with success: true, while carrying exitCode: 1 and the container engine's own text in the stderr field. The command had not run, the answer looked successful, and a caller had to string-match the error text to learn why.

After

Such a call answers 502 with the code CONTAINER_NOT_READY and a hint that leads to deploying the application. Container engine details no longer travel in the response. Clients that expected 200 must handle CONTAINER_NOT_READY as a signal to deploy the application first and then retry the command. No string matching is needed: the code names the cause. If the host agent does not yet support safe container_exec, the platform does not dispatch a legacy command and answers 502 EXEC_FAILED; retry after the host agent is upgraded. Successful commands on a supported agent version are unchanged.

FIX-0826-3: 404 responses for Bitrix24 method names now point to the V1 route

Before

Requests to GET /v1/catalog.product.list, GET /v1/crm.deal.list, GET /v1/crm.user.list, and GET /v1/crm.deal.search returned the generic 404 ROUTE_NOT_FOUND response with only a pointer to GET /v1/guide. An agent had to find the replacement among the V1 routes on its own.

After

These requests still return 404 ROUTE_NOT_FOUND and do not call the Bitrix24 method, but error.details now contains the BITRIX_METHOD_AS_PATH reason, the original method name, a suggestedEndpoint object with the correct HTTP method and path, and a guide object pointing to GET /v1/guide. The hints lead to GET /v1/catalog-products, GET /v1/deals, GET /v1/users, or POST /v1/deals/search.

Impact on integrators

Do not build V1 paths from Bitrix24 method names. When error.details.reason = BITRIX_METHOD_AS_PATH, retry the request using suggestedEndpoint and read guide for the parameter requirements.

FIX-0826-4: Neutral offset in the English createdDate description

Before

GET /v1/task-time/fields used a timezone offset example specific to one region for createdDate.

After

The English description uses the neutral +00:00 offset.

Impact on integrators

No action is required. Only the example in the field description changed.

NEW-0826-5: creating an application from the Cowork/Code desktop — two new endpoints

An application on the Vibecode platform can now be created straight from the desktop, with no trip to the dashboard for a key.

GET /v1/cowork/applications/defaults returns everything the wizard needs before it asks the person anything: the presets for "what portal data does the application need", the access mode the account gives new keys by default, the remaining key quota and the server parameters for the later POST /v1/infra/servers call. The endpoint only reads and creates nothing. A preset carries an identifier and a set of scopes but no labels: the platform owns what a preset consists of, while the client localises the wording by the stable identifier. The placement field has three values rather than two: galaxy-preferred is the ordinary verdict for an account whose policy allows both placements, and it is also where galaxy is demoted for an account on the free tier. When creation is switched off by a platform setting the endpoint answers 200 with available: false instead of a refusal, so the wizard hides its menu entry up front instead of hitting a refusal after the name has been typed.

POST /v1/cowork/applications creates a personal application and mints its personal key, which is returned once. No server is created: a personal application has none by definition — it is grown by publishing, and the server then attaches itself to the card. The card in the response carries the same set of fields the applications catalog returns, so the client still models a single "application" object. Some of the signs are not filled in by this endpoint — read pinning, saved source versions and the running operation from the catalog.

The Idempotency-Key header is required. A repeat with the same body answers 201, the header Idempotent-Replayed: true and rawApiKey: null — the raw key is stored irreversibly and is never re-issued. A lost key cannot be re-minted with the same Cowork/Code key — the response carries no identifier for the issued key, so store it immediately and, if it is lost, create the application again with a new header value. The same header with a different body answers 409 IDEMPOTENCY_KEY_BODY_MISMATCH; the fingerprint is taken over a normalised body, so re-ordered fields and re-ordered scopes still replay.

The Bitrix24 scopes are required and have no default. The issued key carries infrastructure and storage rights plus the Bitrix24 scopes that were asked for, and deliberately does NOT carry AI or web-search rights: an application created by this endpoint does not spend the platform wallet on AI.

Both endpoints require the vibe:cowork scope and an active Cowork/Code subscription. A subscription key issued for third-party agent software is not admitted to them — 403 COWORK_HARNESS_KEY_FORBIDDEN.

FIX-0826-6: work schedule answers with a clear error when the required id is missing

Before

GET /v1/workday/schedule without the required id was forwarded to Bitrix24 and returned 422 BITRIX_ERROR carrying the Bitrix24 text about a missing parameter. The response named neither the parameter in a readable form nor this endpoint, and the machine-readable description did not declare id as required, so a generated client would build such a call itself.

After

A request without id is refused before Bitrix24 is contacted and returns 400 MISSING_REQUIRED_PARAMS, stating that the schedule id is needed, not a user id. The machine-readable description declares id as a required query parameter.

Impact on integrators

A request with id behaves as before. A call made without id now returns 400 instead of 422 — the response was already an error, so working requests need no changes.

NEW-0826-7: an app is no longer granted the `vibe:infra` scope on portals with infrastructure disabled

Before

POST /v1/apps with vibe:infra in the scope list created the app and its key with that scope regardless of whether infrastructure was enabled on the portal.

POST /v1/apps
{ "title": "My app", "scopes": ["crm", "vibe:infra"] }

HTTP 201
{ "success": true, "data": { "scopes": ["crm", "vibe:infra"] } }

After

When the account admin has turned server management off, a request carrying that scope returns 403 INFRA_DISABLED_FOR_PORTAL and no app is created.

POST /v1/apps
{ "title": "My app", "scopes": ["crm", "vibe:infra"] }

HTTP 403
{
  "success": false,
  "error": {
    "code": "INFRA_DISABLED_FOR_PORTAL",
    "message": "Infrastructure is disabled on this portal — the vibe:infra scope cannot be granted"
  }
}

The successful path is untouched: when infrastructure is enabled, the response remains HTTP 201 for the same request. A request without that scope keeps working on a closed account too — the scope is simply not appended by default, and no error is returned.

NEW-0826-8: the `vibe:infra` scope can no longer be added to an app by editing its scopes

Before

PATCH /v1/apps/:id with vibe:infra appended to the scope list wrote that scope onto the app's paired keys regardless of whether infrastructure was enabled on the portal. That path handed a key server access on accounts where creating such a key is refused.

PATCH /v1/apps/{id}
{ "scopes": ["crm", "vibe:infra"] }

HTTP 200
{ "success": true, "data": { "scopes": ["crm", "vibe:infra"] } }

After

When the account admin has turned server management off, adding the scope returns 403 INFRA_DISABLED_FOR_PORTAL and neither the app nor its keys change.

PATCH /v1/apps/{id}
{ "scopes": ["crm", "vibe:infra"] }

HTTP 403
{
  "success": false,
  "error": {
    "code": "INFRA_DISABLED_FOR_PORTAL",
    "message": "Infrastructure is disabled on this portal — the vibe:infra scope cannot be granted"
  }
}

The successful path is untouched: when infrastructure is enabled, the response remains HTTP 200 for the same request. Editing an app that already carries the scope keeps working on a closed account too, and removing the scope is always allowed.

NEW-0826-9: managing a galaxy server is blocked while galaxies are disabled for the account

Before

The galaxy flag was checked on creation only. An already created galaxy server — POST /v1/infra/servers/:id/wake, PATCH /v1/infra/servers/:id/sleep and the other mutating operations — could still be managed after the account admin had turned galaxies off.

POST /v1/infra/servers/{id}/wake

HTTP 200
{ "success": true }

After

While galaxies are disabled for the account, mutating operations on such a server return 403 GALAXY_DISABLED.

POST /v1/infra/servers/{id}/wake

HTTP 403
{
  "success": false,
  "error": {
    "code": "GALAXY_DISABLED",
    "message": "Galaxy feature is not enabled for this portal"
  }
}

When galaxies are enabled, the response remains HTTP 200. Reading (GET), status refresh (POST /v1/infra/servers/:id/refresh) and server deletion stay available at all times: leaving the pilot and cleaning up is possible after the switch-off too. Regular servers are not affected.

NEW-0826-10: the `vibe:infra` scope is no longer granted on portals with infrastructure disabled

Before

POST /v1/keys and PATCH /v1/keys/:id granted the vibe:infra scope regardless of whether infrastructure was enabled on the portal — availability was checked by the dashboard UI only.

PATCH /v1/keys/{id}
{ "scopes": ["crm", "vibe:infra"] }

HTTP 200
{ "success": true, "data": { "scopes": ["crm", "vibe:infra"] } }

After

When the portal admin has turned server management off, adding the scope returns 403 INFRA_DISABLED_FOR_PORTAL.

PATCH /v1/keys/{id}
{ "scopes": ["crm", "vibe:infra"] }

HTTP 403
{
  "success": false,
  "error": {
    "code": "INFRA_DISABLED_FOR_PORTAL",
    "message": "Infrastructure is disabled on this portal — the vibe:infra scope cannot be granted"
  }
}

The successful path is untouched: when infrastructure is enabled, the response remains HTTP 200 for the same request. Editing a key that already carries the scope keeps working even on a closed portal: the gate looks at the scope being added, not at its presence in the request body. Removing the scope is always allowed. On key creation without an explicit request the scope is simply not appended by default — no error is returned.

NEW-0826-11: scope requirements map in the key self-description

GET /v1/me now returns a scopeRequirements field inside data.api — a map of the key's scopes. Until now the only way to learn a key's boundary was to make the call: the request went out and came back with a 403 SCOPE_DENIED refusal naming the missing scope. The list of available entities showed only what was open, while what was closed was simply absent, and absence could not tell "no such entity in the product" from "it exists but your key cannot reach it".

The granted field lists the scopes the key holds, split between Bitrix24 and Vibecode. The missing field lists the absent ones and, for each, which entities and which paths it would open, plus howToObtain — how to get it: Bitrix24 binds scopes to a key when the key is issued, so the only way to gain one is to reissue the key. Path lists are cut at five items and the remainder is reported in unlocksRemaining next to a truncated flag. The unobtainable field lists scopes a personal webhook key can never carry. The aliases field shows spellings Bitrix24 treats as one scope.

The coverage field declares the completeness of the map itself: entities is always complete, while paths is partial for now — some addresses still lack a machine-checked verdict, so the path lists under-report. Absence of an address from unlocks does not prove the address needs no scope: if a call still answers with a refusal, trust the refusal, not the map. Scopes the platform mints itself and a user cannot obtain go to unobtainable, not into missing with impossible advice.

The map describes the platform-side scope check only, as _note warns. It does not promise the call will succeed: a scope granted in the Vibecode account after the key was issued shows up in the map, but Bitrix24 does not honour it and answers BITRIX_ACCESS_DENIED. Refusals by key kind, ownership, read-only mode, account freeze and plan are separate axes and are not described in the map.

Refusals changed in neither code nor text: 403 SCOPE_DENIED still names the missing scope. This adds a pre-flight check, it does not replace the refusal.

FIX-0826-12: bracket-form sorting of task comments, `?sort[field]=direction`

Before

GET /v1/tasks/{taskId}/comments?sort[id]=desc answered 500 INTERNAL_ERROR. The bracket sort form is accepted by /v1/tasks and /v1/deals, and the flat spelling of the same request — ?sort=id:desc — already worked here too, so the failure looked arbitrary. Every bracket sort failed, including an unsortable field: ?sort[createdAt]=desc also answered 500, while the flat ?sort=createdAt returned a clear 400 INVALID_SORT_FIELD listing the sortable fields.

After

The bracket form is parsed like the flat one and goes through the same field-name check. ?sort[id]=desc sorts by ID and answers 200; the flat ?sort=id:desc is unchanged — its response remains HTTP 200. An unsortable field in brackets answers 400 INVALID_SORT_FIELD with the same field list as the flat form, and the error text names the field — Unsupported sort 'createdAt:desc'. A sort value that cannot be read unambiguously (a repeated parameter, mixed flat and bracket forms, nested or malformed brackets, an array, or more than one colon) also answers 400 instead of being silently reinterpreted or dropped. The same bracket-shaped sort on the task-checklist and platform-portals lists now returns a controlled 400 instead of 500. This parameter no longer produces 500 in any form.

FIX-0826-13: waking an app on a failed Galaxy host now ends with an explicit error

Before

POST /v1/infra/servers/:id/start and POST /v1/infra/servers/:id/wake could appear successful for a Galaxy app even after the shared host guest OS had been classified as unable to boot. The client kept waiting for a startup that could never finish.

After

Both requests now return HTTP 422 with code GUEST_NOT_BOOTING for that Galaxy app. The client can stop waiting immediately and prompt the user to replace the failed host.

FIX-0826-14: Bitrix24 registration failures no longer expose the vendor's internal text

Before

When Bitrix24 refused registration while issuing a key or an application, its internal wording was passed straight through in error.message — for example Cannot register webhook: Failed to register webhook in portal. That text is always English, is not covered by the documentation, and could change on the Bitrix24 side at any time. One family of these failures (incoming-webhook registration) also returned the Bitrix24 code directly instead of a Vibecode one.

After

error.message now carries Vibecode wording, and the details of the Bitrix24 reply stay in the logs. A webhook registration refusal is classified the same way as an application registration refusal and returns REST_REGISTRATION_FAILED. The response gains error.details.incidentCode — a six-character support code that lets support locate the log record. HTTP statuses and error codes are unchanged, so no client action is required.

2026-08-25

FIX-0825-1: an application card now gets its server on galaxy portals too

Before

An application created without a server and then deployed on a galaxy portal stayed in the Applications section with no server: GET /v1/applications/{id} returned server: null indefinitely. Linking the container to an already existing card depended on a setting that is off by default, so the card and the container lived apart.

After

The container is linked to the already existing card regardless of that setting, and GET /v1/applications/{id} returns the server right after the deploy. The setting still governs only the creation of a NEW card for an app created on a shared host — its behaviour is unchanged.

BC-0825-2: a read-only key no longer writes on platform endpoints

Old format supported until: not provided

Before

The read-only key mode filtered Bitrix24 calls but did not cover platform V1 endpoints. A read-only key could still manage servers (DELETE /v1/infra/servers/{id}, POST /v1/infra/servers/{id}/stop|start|reboot|wake), deploy and run commands on a server, write to storage (POST /v1/storage/objects), submit feedback (POST /v1/feedback), manage search and AI credentials, and call endpoints that spend credits.

After

Any write on a platform V1 endpoint made with a read-only key returns 403 WRITE_BLOCKED_READONLY_KEY before the operation runs. Endpoints that proxy a call to Bitrix24 are unchanged: there the decision comes from the per-method classifier, so reads that carry a request body (POST /v1/deals/search, a read-only POST /v1/batch, and similar) are not affected.

There are two exceptions. POST /v1/apps — a read-only key can still create an application and its paired key IN read-only mode, but cannot issue a read-write key. DELETE /v1/infra/servers/{id}/lock — releasing a stuck lock does not change server state and stays available: the recoveryAction field of an EXEC_BUSY response points to it.

If your application needs these operations, switch the key to read-write mode on the /keys page. You can check the current mode and whether server creation is available via GET /v1/me: for a read-only key the response now carries a writeRestriction field — the refusal code, the scope it applies to, and the address of the access-mode page. It exists because the response names writing endpoints in some thirty places (storage, feedback, source-storage and cowork hints); those are addresses, not permissions, and the field says so outright. Per-operation availability stays in capabilities.

FIX-0825-3: /v1/me no longer reports app creation as unavailable to a read-only key

In the GET /v1/me response the capabilities.apps.create slot came back with available: false and the reason WRITE_BLOCKED_READONLY_KEY under a read-only key. That was wrong: POST /v1/apps refuses such a key only when it asks for an app and paired key in read+write mode, while an app in READ-ONLY mode is created by the same key and answers 201.

The slot is now reported as available, with the restriction spelled out in its note field. A client that branches on capabilities — which is what /v1/me exists for — no longer skips an operation that works.

BC-0825-4: a Cowork desktop key can no longer change OAuth application registrations

Old format supported until: not provided

Before

A key carrying the system vibe:cowork grant could register an OAuth application on the Bitrix24 account (POST /v1/apps), edit it (PATCH /v1/apps/{id}), delete it (DELETE /v1/apps/{id}) and re-point it at other credentials (POST /v1/apps/{id}/relink-oauth). The same key was already barred from infrastructure, the source depot and catalog publishing, so the restriction was incomplete.

After

All four operations answer 403 INFRA_FORBIDDEN_FOR_COWORK_KEY, with details.deployableKeys listing the owner's usable keys. On POST /v1/apps the refusal comes before the body is checked, so an invalid body also gets this code rather than VALIDATION_ERROR. Reads of the family (GET /v1/apps, GET /v1/apps/{id}) are unchanged.

What to do

Run these operations under an ordinary application key: the vibe:cowork grant is platform-minted and meant for data only. Candidate keys arrive in details.deployableKeys of the same response — name, prefix and trailing characters, never the secret. There is no support window for the old behaviour: the vibe:cowork grant is not user-grantable, never appears in the key dialogs, and its only holder does not call these operations.

BC-0825-5: re-uploading a file now replaces its content instead of failing with 500

Old format supported until: not provided

Before

Uploading to a logical key that was already taken returned 500 with code P2002 from POST /v1/storage/objects/upload. The bytes in storage had already been overwritten, while the object sizeBytes and sha256 still described the previous version — so the size shown in listings and billing did not match the actual file.

After

Re-uploading to the same key replaces the content: 200, the same object.id (previously issued links keep working), and sizeBytes, sha256, contentType and the new contentUpdatedAt field match the new bytes.

This applies to an app-bound key. With a personal developer key that has no app binding, re-uploading still creates a new object with its own id — unchanged behaviour, fixed separately.

When the object cannot be replaced in place, a 409 with a meaningful code is returned instead of 500: STORAGE_KEY_DELETED (the object is deleted and holds the name until the purge), STORAGE_MULTIPART_IN_PROGRESS (a multipart upload is in progress), STORAGE_UPLOAD_PENDING (the key holds an unfinished presigned reservation), STORAGE_KEY_OWNED_ELSEWHERE (the name belongs to another object of this app), STORAGE_KEY_CONFLICT (the object changed while the upload was in flight — retry).

What you need to do

1. The visibility field cannot change visibility while replacing: omit it or pass the current value. Any other value returns 400 STORAGE_VISIBILITY_MISMATCH, and the current value is named in the message. Such a request used to return 500 while still replacing the bytes — so a client that ignored the error was in fact publishing updates and will stop doing so after this change.
2. A presigned URL (POST /v1/storage/objects) is no longer minted for an existing object: 409 STORAGE_KEY_EXISTS. Its Content-Type is unsigned, so content can only be replaced by a direct upload. An unfinished reservation of your own is reused instead — 200 with the same object.id and a fresh URL; such a URL cannot change the reservation visibility, so a differing value returns 400 STORAGE_VISIBILITY_MISMATCH.
3. A multipart upload (POST /v1/storage/objects/multipart/create) on a taken key also answers 409 instead of 500: STORAGE_KEY_EXISTS, STORAGE_KEY_DELETED, STORAGE_MULTIPART_IN_PROGRESS, STORAGE_UPLOAD_PENDING or STORAGE_KEY_CONFLICT (a concurrent request created the object). Replacing an object through a multipart upload is not supported — use another key.
4. Responses now carry object.contentUpdatedAt — when the content last became current. It is null for objects written before this change.

BC-0825-6: the binding and author fields of a timeline comment no longer look editable

Old format supported until: not provided

Before

GET /v1/timelines/fields returned entityType, entityId and authorId as ordinary writable fields. PATCH /v1/timelines/{id} with any of them answered 200 and success: true, yet the value did not change — reading the record back showed the previous one. Meanwhile id and createdAt in the same output were honestly refused with 400 READONLY_FIELD, so the field reference told the truth only selectively. An integrator or an AI agent concluded it had changed the author or moved the comment to another record, while nothing had changed at all.

After

The three fields are marked immutable in the field reference, and an attempt to write them is refused with 400 READONLY_FIELD instead of a silent success. The reasons differ per field, and the reference now distinguishes them:

• entityType and entityId — available on create only: a comment is bound to its record at the moment it is added, and it cannot be moved to another one;
• authorId — read-only: Bitrix24 derives the author from the credentials the call is made with, so the value cannot be set on update or on create.

comment stays writable — it is the only field the Bitrix24 update accepts.

What integrators should do

Drop entityType, entityId and authorId from the body of PATCH /v1/timelines/{id} — they were never applied, and now a request carrying them returns 400 READONLY_FIELD. Check creation separately: POST /v1/timelines carrying authorId also moves from "201, value ignored" to 400 READONLY_FIELD, because the author cannot be set on create either. entityType and entityId stay required and accepted on create. If your code treated the successful answer as proof that the author had changed or the comment had moved, that expectation was already unmet before this change: the value stayed as it was. The comment text still updates through a normal PATCH with the comment field. Set the binding at creation time through POST /v1/timelines; the author cannot be changed — make the call under the account you need.

No support window for the previous behaviour is provided, deliberately: the previous behaviour was the defect — it silently discarded the value that was sent, and keeping it for a period would mean prolonging a silent data loss.

BC-0825-7: deploy base version is required when the top saved source version belongs to somebody else too

Old format supported until: not provided

Before

POST /v1/infra/servers/{id}/deploy required baseVersionId only on a server that currently had a live development team. If the owner added a teammate, the teammate deployed their own version, and the owner later removed them from the team, the requirement disappeared along with the last team member — and the next deploy silently overwrote the saved work.

After

baseVersionId is also required when the top version saved in the server's source depot was saved by somebody other than the caller deploying now — regardless of whether the server currently has a team. The error is unchanged: 409 BASE_VERSION_REQUIRED naming the current version.

What integrations must do

Send baseVersionId on every deploy. A client that already does needs no changes. A client that relied on "no team means no label needed" will get 409 BASE_VERSION_REQUIRED on a server holding somebody else's saved version — including after an application ownership transfer, where the top version was saved by the previous owner. Handle it the way the team case is already handled: read the current version number from the error body and repeat the deploy declaring it as the base. The old behaviour is not kept for any period: it is exactly what caused other people's work to be lost.

NEW-0825-8: a server's development-team member now sees its application in the catalog

A member of a server's development team now sees the application bound to that server in GET /v1/applications (arriving with viewerState: "shared") and can read its card via GET /v1/applications/{id} — previously the card answered 403 FORBIDDEN, because access was checked only by ownership and by the server's access policy, without considering team membership.

FIX-0825-9: include is advertised only for entities with relations

Before

OpenAPI and the MCP reference advertised the include parameter for list, get, and search on every entity. For entities without available relations, a request with this parameter returned 400 INVALID_INCLUDE with an empty list of available relations.

After

OpenAPI advertises include only for entities with available relations, while the MCP reference directs clients to check the capability through discover or get_fields first. Runtime validation and the 400 INVALID_INCLUDE response for an unsupported include are unchanged.

Impact on integrations

Client generators no longer receive an unsupported include from OpenAPI, while MCP agents get explicit guidance to check the capability first. The common optional MCP key remains available. Existing valid requests continue to work unchanged, while previously unsupported requests receive the same 400 INVALID_INCLUDE response.

BC-0825-10: Inline archive cap on the deploy body narrowed to 96 MB

Old format supported until: not provided

Before

POST /v1/infra/servers/:id/deploy with code in inline source.content, POST /v1/infra/servers/:id/upload with inline content, and POST /v1/infra/servers with the source field at creation accepted a body up to 500 MB. A body over the cap was refused with PAYLOAD_TOO_LARGE.

After

The body of these three requests is capped at 96 MB. The unit is the HTTP body itself, not the archive: source.content / content is base64, which runs about a third larger than the raw bytes, so a 96 MB body corresponds to roughly a 72 MB archive. A body over the cap is refused with 413 INLINE_SOURCE_TOO_LARGE — a new code, replacing the former PAYLOAD_TOO_LARGE on these three endpoints. The refusal is decided from the Content-Length header before the body is read, so it is deterministic — re-sending the same body fails identically. It saves no traffic: the whole body is uploaded first, and the refusal arrives once the upload has finished. The error envelope carries error.hint with reason, recovery, recoveryAction and note fields — a ready recovery recipe.

The multipart (multipart/form-data) form of POST /v1/infra/servers/:id/deploy falls under the same cap conditionally. The file part streams into storage — and keeps its former 500 MB archive limit — only when three conditions hold at once: the caller reaches the server as its direct owner, not through another application's card or a management key; the server is either not a galaxy app, or both link-based-deploy settings for galaxy apps are turned on for the caller; and the source storage feature is enabled, both platform-wide and for that portal. If even one condition fails, streaming does not kick in and the form accepts the archive the same buffered way as the base64 fields above — under the same 72 MB archive cap, with the same 413 INLINE_SOURCE_TOO_LARGE code and error.hint.

The former PAYLOAD_TOO_LARGE code has not gone away: it still applies at the edge nginx layer on /v1/ (500 MB cap) and on every other platform route with its own limit — nothing was renamed.

Unchanged:

• source.url — still accepted up to 500 MB; the platform downloads the archive from the link itself;
• source.versionId — deploying an already-saved version, up to a 500 MB archive;
• the source-version save cap on POST /v1/infra/servers/:id/sources and POST /v1/apps/:id/sources — 500 MB, untouched.

What integrators should do

Send an archive larger than 72 MB through the versioned path in two calls — it works the same way for a personal key (vibe_api_*) and for an OAuth-app key, and for the server's direct owner these two calls are all it takes:

POST /v1/infra/servers/:id/sources   # raw archive bytes, Content-Type: application/gzip, --data-binary
POST /v1/infra/servers/:id/deploy    # {"source":{"versionId":"vN"}}

If, on the other hand, the server is reached through an application card or a management key rather than by its direct owner, those two calls take a third one: {versionId} may answer SOURCE_VERSION_REQUIRES_APP or SOURCE_VERSION_NOT_FOUND — in that case fetch a signed link at GET /v1/infra/servers/:id/sources/vN/download and deploy from it instead: {"source":{"url":"<link>"}}. This same path is also the way around the multipart form's conditional cap — a versioned deploy never buffers the whole archive, so its 500 MB limit is unconditional.

The cap was narrowed at the observable-behavior level: a body of several hundred megabytes in base64 form (and a multipart archive for which at least one of the conditions above did not hold) had to be held in memory whole for the duration of the request, and such a request could abort without a response, taking concurrent requests on the same process down with it.

NEW-0825-11: `GET /v1/me` now names the archive equivalent of the inline cap as its own field

Before

The deployment.limits block carried the inline body cap in a single uploadInlineMax field. Its unit is the HTTP body, while source.content and content travel as base64, so the archive size that fits into that body was left for the client to work out.

After

A sibling field uploadInlineMaxArchive was added — the same cap expressed as an ARCHIVE size: three quarters of uploadInlineMax, because base64 runs about a third larger than the raw bytes. The field is added to the response and removes nothing from it: uploadInlineMax stays where it was and means what it meant, so a client that ignores the new field needs no changes. Both values arrive as strings with a unit — for example 96MB and 72MB.

What integrators should do

Nothing is required. If you were converting the body cap into an archive size yourself, read uploadInlineMaxArchive instead — it is rendered from the same constant as the 413 INLINE_SOURCE_TOO_LARGE refusal, so it cannot drift from the actual behaviour.

BC-0825-12: POST /v1/apps now honours the portal policy for who may create apps

Old format supported until: not provided

Before

The public route only checked the legacy list-based mode. A portal whose Bitrix24 admin had limited app creation to admins, or disabled it entirely, still let any personal API key create an app — while the same action in the dashboard answered 403.

After

POST /v1/apps answers 403 with code APP_CREATION_RESTRICTED when the portal policy does not allow the caller to create apps. The list-based mode behaves as before: a member on the list creates the app, everyone else gets 403. On portals where creation is open to all, nothing changes.

What integrators should do

A key issued on a restricted portal will start receiving 403 APP_CREATION_RESTRICTED where it previously got 201. Ask the Bitrix24 admin to grant the app-creation right, or create apps with a key that already holds it.

FIX-0825-13: Node.js 20 runtime setup no longer repeats completed steps

Before

When redeploying a Node.js 20 runtime through POST /v1/infra/servers/:id/deploy, the platform reinstalled Node.js and pm2. An unavailable npm registry could consume the entire step budget and finish without a precise cause.

After

The platform skips installation when Node.js 20 and pm2 are already available. If pm2 is absent, its installation has time and retry limits, and an error or timeout stops deployment with an explicit diagnostic.

Impact on integrators

Repeat deployments finish faster and require no integrator changes. A pm2 installation error is now immediately visible as the cause of an unsuccessful deployment.

FIX-0825-14: placement bind answers 400 for an over-long iconName instead of a reasonless 502

Before

POST /v1/placements/bind accepted an options.iconName of up to 255 characters. Bitrix24 refuses anything longer than 50, so the request travelled to the account and came back as 502 BITRIX_UNAVAILABLE carrying "Failed to register placement on Bitrix24 via dev key". Which field was at fault could not be told from the answer.

After

The schema bound now matches the Bitrix24 bound: a value longer than 50 characters is refused up front, and the 400 names the options.iconName field. Values that bound before keep binding — anything longer than 50 was never accepted by the account, and the default fa-cube icon sits well inside the bound.

2026-08-24

BC-0824-1: activity type can no longer be changed after creation

Old format supported until: not provided

Before

PATCH /v1/activities/:id accepted the typeId field. The value never reached storage: an activity type is fixed at creation, so it was discarded. A request carrying typeId as its only field ended up with an empty field set and returned the opaque refusal Fields is not specified., which gives no hint that immutability of the type is the reason. A request that also carried at least one writable field answered with success, so the caller believed the type had changed.

After

typeId is declared as a field that is set only on creation. PATCH /v1/activities/:id carrying it returns 400 READONLY_FIELD and names the field. Both batch update operations answer the same way. POST /v1/activities still accepts the field, where it stays mandatory. In the GET /v1/activities/fields output, typeId now carries the createOnly marker.

What integrators should do

Remove typeId from the body of PATCH /v1/activities/:id. If the type genuinely has to change, create an activity with the required type and delete the previous one — the type of an existing activity cannot be edited. The createOnly marker in the GET /v1/activities/fields response lets you tell such fields apart before sending a request.

FIX-0824-2: paid accounts no longer receive an error asking them to pay again

Before

POST /v1/apps could return a 403 error asking a paid account to upgrade when application installation through Bitrix24 failed.

After

When Bitrix24 confirms that the plan is paid, the method returns the technical error 502 CONNECTOR_REST_UNAVAILABLE with a safe reason and no upgrade prompt. A confirmed unpaid plan still returns a 403 plan error.

Impact on integrations

Requests require no changes. The technical error can be retried, while the plan error requires an upgrade.

BC-0824-3: the deployment block changes shape for Belarusian accounts along with their access model

Old format supported until: not provided

Before

An account licensed in Belarus landed in the limited-access bucket under three conditions at once: it held a demo subscription, it held no paid subscription, and it had no history of commercial payments. Its Bitrix24 plan — paid or free — did not affect membership, whereas an account that had ever paid before did not land in the bucket at all. In GET /v1/me such an account received a deployment block with no galaxyApp sub-block, with primary = standalone and with a placementNote field explaining that no galaxy host of its own is created for it and that an app must be deployed in two steps. A one-shot create carrying source answered 400 SOURCE_AT_CREATE_GALAXY_ONLY.

After

The plan-based model has no limited-access bucket at all, so a Belarusian account leaves it in both directions at once: on a paid or demo Bitrix24 plan it gets full access, on a free plan it is denied. In both cases the deployment block changes shape the same way — provided galaxy placement is open to the account and it does not yet have a galaxy of its own (both carve-outs are named below): the deployment.galaxyApp sub-block appears, the deployment.placementNote field disappears, and deployment.primary switches from standalone to galaxyApp. For an account with full access a one-shot create carrying source starts working.

What integrators should do

Detect the placement model by the PRESENCE of the deployment.galaxyApp sub-block, exactly as the response reference prescribes. Rewrite any branch keyed on the presence of placementNote or on the value of primary: both fields move with the account's access model, not only with its plan. Read the permission to create a server separately, from capabilities.servers.create: the deployment block describes the placement CONTRACT and is present for a denied account too, while POST /v1/infra/servers answers such an account with 402. Two carve-outs where the response shape does not change at all. The first is an account with galaxy placement switched off: neither field is present before or after. The second is an account that already has a galaxy: placementNote explained the absence of a galaxy of its own, so the owner of a live galaxy host received galaxyApp and no placementNote while in the bucket too. The change reaches an account at the moment it is moved onto the plan-based model, so both response shapes occur side by side across accounts.

NEW-0824-4: the Bitrix24 plan becomes the access condition for accounts licensed in Belarus

Vibecode admits an account to the infrastructure either by its Bitrix24 plan or by a subscription, depending on the licence region the account belongs to. Accounts licensed in Belarus — served by a separate Vibecode deployment, not by this one — move onto the plan-based model: a paid or a demo Bitrix24 plan grants access there, and an account with neither is declined. The move is staged, account by account.

Nothing changes on this deployment and no action is required. Access here has always been granted by the Bitrix24 plan alone: a commercial plan grants full access, a demo plan grants a limited trial, and on a free plan POST /v1/infra/servers — like an app publish, a wake of a sleeping machine or the issuance of a new key — is still declined with 402 and INT_TARIFF_REQUIRED, which GET /v1/me also reports in capabilities.servers.create.reason. No new field, no new denial code and no new branch appear in the contract you consume here.

FIX-0824-5: the server-creation hint in the key response no longer leads nowhere

Before

An account whose access is granted by a Bitrix24 plan rather than a subscription received a capabilities.servers.create slot in GET /v1/me carrying a generic wording: servers are available on commercial plans or during an active trial. That was wrong twice over. Such an account is not entitled to the trial — the entitlement is computed on the subscription model — and the address where a plan is chosen was not named at all. Separately, for accounts licensed in Belarus the alternatives[].url field pointed at the subscription checkout inside the account itself, and would have kept pointing there after the account moved onto the plan-based model, where a subscription no longer resolves the denial.

After

The slot names the working paths and the address: a paid or demo Bitrix24 plan, and for Belarus a paid subscription as well. The text in capabilities.servers.create.userMessage now matches the 402 body that POST /v1/infra/servers returns for the same account — one denial code no longer says different things on two surfaces. For accounts licensed in Belarus that have moved onto the plan-based model, alternatives[].url points at the plan-selection page instead of the subscription checkout.

Impact on integrators

No action required: a text field and a URL changed value, the response structure is unchanged. The fix reaches Kazakhstan and Uzbekistan at once, and Belarus as each account is moved onto the plan-based model. If you render your own copy instead of userMessage, review it: the promise of a trial is wrong for these accounts.

FIX-0824-6: the denial text for Kazakhstan and Uzbekistan no longer offers a subscription

Before

On the deployment that serves Kazakhstan and Uzbekistan an account on a free plan was refused with the subscription-model text and was asked to activate a subscription that is not sold in those countries. The action named in the text could not be performed, and the working paths to access — a paid or a demo Bitrix24 plan — were not named at all, nor was the address where a plan is chosen.

After

Such an account is now refused with the plan-based code of its own region, and the text names both working paths and the address. The subscription brand is gone from it. The correction reaches every surface where an access denial is visible to the client: server creation (POST /v1/infra/servers), an app publish, a wake of a sleeping machine and the issuance of a new key, as well as capabilities.servers.create.reason in GET /v1/me.

Nothing changes on this deployment and no action is required here. Access on this surface is granted by the Bitrix24 plan alone, a free-plan denial is still answered with 402 and INT_TARIFF_REQUIRED, and neither the request nor the shape of the response changes. The regional denial codes corrected above are reachable only on the deployment named there.

BC-0824-7: bot re-authorization is now explicit and safe

Old format supported until: not provided

Before

POST /v1/bots/:botId/reauth could clear any disabled bot state, while 410 BOT_DISABLED did not tell clients whether automatic recovery was allowed.

After

410 BOT_DISABLED includes boolean error.details.reauthAllowed. Call POST /v1/bots/:botId/reauth automatically only when reauthAllowed=true; the server emits that signal only for writable bots disabled by authentication failures and enables it gradually. A manual call also remains the credential probe for an active bot after ownership transfer. Other disabled states now fail immediately with 409 BOT_REAUTH_NOT_ALLOWED; a concurrent state change returns 409 BOT_REAUTH_STATE_CHANGED. Update clients that called re-authorization for every BOT_DISABLED response.

FIX-0824-8: galaxy application deploy warns when environment variables are reset

Before

A successful /deploy without user env recreated the galaxy application without previous variables but did not report that in the response.

After

The response includes a warnings[] entry asking callers to send the complete env on every deploy. A development-team member's deploy, where the owner's variables are preserved, receives no false warning.

Impact

The deploy status and behaviour are unchanged; clients should read the existing warnings[] array.

NEW-0824-9: task dependencies are now available through the API

Before

The Bitrix24 task card shows a "Related tasks" block, but there was no way to read those links through the API: no dependency fields in the task list, none in a task read by id, nothing about them in the task field description, and no dedicated endpoint. A dashboard that needed the dependency graph could not build it.

After

Two read-only endpoints were added. GET /v1/tasks/:taskId/dependencies returns the dependencies of one task as an array of id-and-title pairs, sorted by id. POST /v1/tasks/dependencies/bulk takes up to 50 tasks and answers per task: successes in results, failures in errors, counters in meta.

The bulk call answers 200 even when every sub-call failed — partial failure is the whole point of it, so what has to be read is errors, not only results. Duplicate ids collapse silently and the requested counter counts unique ids, so "requested" always equals "succeeded" plus "failed".

Boundaries, stated explicitly

Only predecessors are returned — the tasks the requested one depends on. Bitrix24 exposes no reverse direction through the API, so a dashboard builds it by inverting the pairs it collected. The link type is readable by no portal method, so it is absent from the response entirely: an empty or guessed value in a contract is worse than a missing field.

Links added through the Gantt chart are invisible to these endpoints: the portal keeps them separately and returns them from no read method. Telling "there are no links" apart from "there are links, in the invisible store" is impossible here and in raw REST alike.

A task carrying more dependencies than the endpoint returns gets an explicit refusal rather than a truncated list: the response is either complete or a refusal.

Impact on integrators

There are no breaking changes — both routes are new. Writing dependencies did not get an endpoint of its own: the set is still changed through the DEPENDS_ON field on task update, and the semantics there are a full replacement of the set rather than an addition.

FIX-0824-10: international bot access keeps the Bitrix24 plan model

Before

The international instance already governed account access through the Bitrix24 plan model. Bot permission failures returned 403 BITRIX_ACCESS_DENIED.

After

There is no change to that .com contract: bot access stays on the international plan model. GET /v1/me?refresh=tariff continues to refresh the account's Bitrix24 plan state after an upgrade.

What integrators should do

Keep handling international access through the existing plan errors. No new bot error branch is required on .com.

BC-0824-11: opening a workday no longer confirms an expired state

Old format supported until: not provided

Before

POST /v1/workday/open returned 200 success:true when Bitrix24 left the workday in the EXPIRED status. No new workday was opened.

After

An unchanged EXPIRED status is returned as HTTP 409 with success:false and the WORKDAY_EXPIRED code. The instructions say to read status for the same user, close the expired day using its timeStart date and a report, and then retry open.

What integrators should do

Handle success:false and HTTP 409 as an explicit signal that the workday was not opened; resolve the previous day's state using the response hint first.

NEW-0824-12: calendar events can be linked to CRM elements

A calendar event now carries a crmFields field — the link between a meeting and CRM elements: deals, leads, contacts and companies. The field is readable and writable, is declared in GET /v1/calendar-events/fields, and is available in select.

The value is an array of typed references: D_<id> deal, C_<id> contact, L_<id> lead, CO_<id> company. On create and update the value must be an array; [] clears every link, and omitting the field from the body keeps the stored ones. Clearing with an empty array works on POST and PATCH; in a batch request an empty array is refused rather than silently succeeding — a batch sub-call cannot carry one. On POST /v1/batch that is INVALID_PARAMS in data.errors under the call's id; on POST /v1/calendar-events/batch it is 400 BATCH_ITEM_VALIDATION for the whole batch, with the name INVALID_PARAMS and the item index inside message. An event with no links reads back as [] — the empty value never arrives as null or an empty string, so a crmFields.length check is always safe. An unknown prefix, or a reference to a record that does not exist, is rejected.

Affected endpoints: GET /v1/calendar-events, GET /v1/calendar-events/:id, POST /v1/calendar-events/search, POST /v1/calendar-events, PATCH /v1/calendar-events/:id, GET /v1/calendar-events/fields.

FIX-0824-13: an application on a galaxy host that does not boot can be deleted without a live tunnel

Before

DELETE /v1/infra/servers/{id} on a galaxy application answered 502 with the code GALAXY_HOST_UNREACHABLE whenever the host was offline, whatever the reason. When the host guest operating system does not boot at all (the provisionErrorCode field of the server record equals GUEST_NOT_BOOTING), the tunnel will never come back, so retrying helped neither a minute later nor a day later. Deleting the host itself was blocked too: it answered 409 with the code GALAXY_HAS_APPS, because its applications formally remained alive. The owner ended up in a closed loop, still holding a quota slot with a machine that no longer runs.

After

Once the platform has proven that the host guest operating system does not boot, an application on that host is deleted without contacting the host: DELETE /v1/infra/servers/{id} answers 200, the application record is closed, and its access tokens, domain and catalog item are released. After deleting the applications one by one, the owner deletes the host itself with the regular call — the GALAXY_HAS_APPS refusal no longer appears. The GALAXY_HOST_UNREACHABLE code keeps its previous meaning for every other case: the host is temporarily offline and retrying makes sense. Important: the does-not-boot mark alone does not guarantee the 200: before deleting without contacting the host, the platform also confirms through the gateway that no live tunnel exists. That check is fail-safe — an unreachable gateway, an answer without a connection list, or a host that came back meanwhile all keep the answer at 502. Clients need no changes — the retry loop for this state simply stops being necessary.

BC-0824-14: an unknown select field name is refused with 400 on almost every entity

Old format supported until: 18.02.2027

Until now such a request answered 200 with the requested field simply missing from the records — so the "old format" here means an incomplete answer, not a working one.

Before

A field name the entity does not have went into the selection silently. The request ran, the field was absent from the records, and the explanation sat in meta.warnings — where nobody looks. A typo in select therefore looked like a successful request with mysteriously incomplete records:

GET /v1/deals?select=id,titel      →  200, records carry only id

Only calendar events answered such a name with an error.

After

The request is refused before the Bitrix24 call — 400 with the UNKNOWN_SELECT_FIELD code and the list of accepted names in the message. That list is the precise answer to "what may I ask for".

It applies to the entities whose field set has been verified against Bitrix24: deals, contacts, companies, leads, quotes, activities, addresses, smart processes, products and product sections, catalogs with their products and sections, orders and order statuses, statuses, currencies, calendar sections, files, folders, storages, departments, workgroups, document templates. Everywhere else the behaviour is unchanged — a warning in meta.warnings.

A separate class is a name the entity DOES have but never returns: GET /v1/{entity}/fields shows such a field with notReturned: true. In this cohort that is, for example, currencyId on products and sort on product sections. It is refused with a 400 too, but under its own SELECT_FIELD_NOT_RETURNED code and a message that names the reason. The separate code is deliberate: UNKNOWN_SELECT_FIELD claims the name does not exist, while the entity's own field catalogue publishes it — a client that honestly took the name from there would otherwise read the answer as "the catalogue is lying".

Only the name is checked. Custom fields (UF_*, ufCrm*) are accepted as before on every entity; product properties are each accepted on THEIR OWN entity: PROPERTY_295 on products, property295 on catalog products, where their numbers are assigned by the portal; the other spelling is not understood by the method and the gate rejects it. A * (or UF_*) value still means "return every field", and a typo next to it causes no refusal — a warning arrives instead. In both batch calls — the global one and the per-entity one — the selection refuses only its own sub-call while neighbouring ones still run.

What integrators should do

Check the field names in your select against the list in the error message or against the GET /v1/{entity}/fields schema. A request that used to "work" but returned records missing some of the requested fields will now answer 400 naming exactly which name was not found — which was its original mistake.

FIX-0824-15: the `datePeriod` field schema is now visible in `GET /v1/bookings/fields`

Before

The datePeriod field was described as "type": "object" with no nested schema. The shape of the object could not be learned from the contract itself — a client would send {} or a date string, get 422 BITRIX_ERROR, and could only guess the required keys from the error text.

After

Fields of type object with a known nested shape now carry a properties key holding a recursive schema of the nested keys. For datePeriod that is from and to, each with timestamp (number, Unix seconds) and timezone (string, an IANA zone name). The same key now appears for requisiteLink in GET /v1/orders/fields, and on both surfaces at once — fieldsDetailed in GET /v1/guide carries it too, so the shape is visible without portal tokens. Arrays of objects still carry no element schema. The change is additive: existing field-description keys stay in place, and create-time validation was not tightened.

NEW-0824-16: Scrum kanban stages and sprint listing in the API

Four operations for working with the columns of a Scrum board. Stages belong to a sprint rather than to a workgroup — different sprints of one project hold independent sets of columns — so the collection is addressed through the sprint.

GET /v1/scrum/sprints returns the sprints of a project. It is the only way to obtain the sprintId the other three operations need; without the groupId parameter it returns every sprint the key can see.

GET /v1/scrum/sprints/:sprintId/stages returns the columns of a sprint, converting id, sort and sprintId to numbers. POST /v1/scrum/sprints/:sprintId/stages creates a column and returns it re-read in full, including the defaults Bitrix24 substitutes. PATCH /v1/scrum/stages/:stageId renames, recolours and reorders a column.

Platform-side validation closes the places where Bitrix24 answers with success and stores something else: a name longer than 255 characters, a colour longer than six characters and a type outside NEW, WORK, FINISH now get a clear refusal instead of a silent substitution. A colour may be sent with a leading #, which is stripped.

Moving a column to another sprint is not exposed: sprintId in the request body is rejected. Updating a stage that does not exist, or that belongs to a project the key cannot access, answers STAGE_NOT_FOUND_OR_NO_ACCESS — the two cases cannot be told apart, because Bitrix24 answers both identically.

FIX-0824-17: ACCOUNT_FROZEN is now documented on server creation

The 402 response of POST /v1/infra/servers listed only the plan, trial and Marketplace-subscription refusals. It omitted ACCOUNT_FROZEN, the code the platform answers to a portal whose wallet is frozen, even though the endpoint already returned it: the balance check runs ahead of the handler, and server creation is not exempt from it.

Because of the omission, a client generated from /v1/openapi.json treated the code as impossible and dropped a refusal that has a clear remedy — top up the balance. Endpoint behaviour is unchanged; only the description was.

2026-08-23

BC-0823-1: OpenAPI no longer offers create-only fields in PATCH

Old format supported until: not provided

Before

Fields accepted by the API only when creating a record appeared in GET /v1/openapi.json as ordinary PATCH body properties. A client generated from that schema could send them on update and receive 400 READONLY_FIELD.

After

For entities with create-only fields, PATCH uses a separate input schema without those fields. Other entities keep using their existing PATCH input schema. In both cases, the POST input schema preserves the create contract.

What integrators should do

Regenerate the SDK from the new OpenAPI schema and use the type referenced by each PATCH requestBody. Affected entities use UpdateInput; other entities keep Input. Remove fields allowed only during creation from update payloads; POST continues to use Input.

NEW-0823-2: several employees can work on one application's code

A server owner can now assemble a development team: portal employees work with the server using their own personal keys, with no key handover and no server rebinding. The Developer role gets deploy, exec, upload, logs and the source depot; the Admin role additionally manages the machine: lifecycle (stop, start, reboot, sleep schedule, repair), settings and security, plan and disk, backups, the custom domain, the catalog card, the application audience and the costs. Team membership, server deletion, access links and key rebinding stay with the owner. Team membership is edited by the owner or a portal administrator on the Collaboration tab.

Access comes from membership, not from the key, so removing somebody from the team closes their access immediately. The feature is gated by the server-collaboration flag.

A team member's deploy differs from the owner's in three ways. Environment variables are preserved: the env field of their request is not applied (the response carries a warning), and the variables already set on the application survive the deploy — including galaxy applications, where every deploy used to wipe them. The Bitrix24 catalog card and the release announcement stay with the owner: displayName, description and the changelog announcement sent by a Developer are ignored with a warning, while the version note itself is still stored in the source depot.

There is also an overwrite guard: the baseVersionId field in the body of POST /v1/infra/servers/:id/deploy ("this is the source version I based my work on", e.g. v12). If a newer version has appeared in the depot, the deploy is refused with SOURCE_VERSION_STALE, carrying the current version number and a download link — instead of silently overwriting.

The declared version is checked for existence: a number ahead of the depot is refused with BASE_VERSION_NOT_FOUND and the current version number — otherwise any non-existent number would switch the guard off.

On a server whose owner has assembled a development team the field is required as soon as the depot holds any version: a deploy without it answers BASE_VERSION_REQUIRED and names the current version. A blind deploy over a colleague's changes is therefore refused even when nobody knew about the guard. On a server without a team the field stays optional and a deploy without it behaves exactly as before. So that the version number has somewhere to come from, the version-download response now carries a versionId field next to the link — see Source code storage.

A 409 EXEC_BUSY refusal now names whoever is holding the server: error.hint.holder carries the employee name, the kind of operation and when it started, and error.hint.reason begins with that name. A background platform operation has no human behind it, so holder.name comes back empty there. The field is additive — the existing fields of the refusal are unchanged.

A team member now sees the server in the API instead of working with it blind. GET /v1/infra/servers also returns the servers whose development team the caller belongs to: those rows carry an access block with via: "collaborator", the role, the allowed actions and the endpoints open to them, while the key's own rows carry access.via: "owner". GET /v1/infra/servers/:id answers a member with 200 and a reduced card (no IP, no SSH access, no managing key; costs and the sleep threshold follow the role) instead of the former 404. GET /v1/me lists the memberships in infra.collaboratorServers. Waking the machine, POST /v1/infra/servers/:id/wake, is open to the Developer role as well — the matrix promised it before, but the call answered 404. Searching for an employee to configure the audience, GET /v1/infra/servers/:id/b24-users, is open to the Admin role — it used to answer a refusal even though that same role already configures the audience itself.

Additionally: a team admin can now perform, via their own personal API key, every server operation their role allows — lifecycle control (stop, start, reboot, sleep, manual repair, wake schedules, metrics), settings (SSH access, port, portal event subscriptions, switching the BLACKHOLE/OPEN mode via PATCH /v1/infra/servers/:id/mode), the catalog card (PATCH /v1/infra/servers/:id — name and description), and access audience (access policy, user/department access list). Previously these operations returned 403/404 via a member's V1 key regardless of role — they only worked from the Vibecode dashboard. V1 membership lists can now return a page: GET /v1/infra/servers accepts optional page and limit and returns a true total alongside. Without the parameters the response is unchanged and complete — the contract stays as published. In /v1/me the infra.collaboratorServers block gained a total field.

Deleting source versions stays with the owner: DELETE /v1/infra/servers/:id/sources/:versionId and the bulk POST /v1/infra/servers/:id/sources/cleanup answer a team member of any role with 403 NOT_AUTHORIZED. Listing, downloading, depositing and tagging remain open to them.

A member's deploy that must preserve the environment refuses to run when the environment cannot be read: instead of silently deploying with an empty environment it answers 502 GALAXY_PRESERVED_ENV_UNREADABLE with a retryable marker. The application keeps running its previous version.

A role refusal is now distinct from "no such server". A management operation not covered by the member's role answers 403 SERVER_ROLE_FORBIDDEN; error.hint carries their role, the role required, the denied action and the endpoints that are open to them. For an unrelated key the existence of the server stays hidden — it still gets a 404.

An app whose owner has been deleted survives only while its team still has an admin — someone who can take it over. A team of developers alone does not hold the app: nobody can manage it, so it is cleaned up like any other ownerless app.

The appUrl field in GET /v1/infra/servers, GET /v1/infra/servers/:id and GET /v1/me (the infra.collaboratorServers block) no longer promises a team member a link they are not allowed to open. Previously the field came back non-empty as soon as the server had a subdomain, regardless of whether the application's audience actually let that particular person open it — following such a link answered with a refusal. Now appUrl is empty whenever the audience (accessPolicy) does not open the application to every portal employee and the member has no personal access grant. There is one exception: a member whose access comes through a department grant does not see the link yet even though they could open the application — for now the server's owner or team admin has to hand it to them directly.

FIX-0823-3: platform public URLs no longer point away from the stand

Before

OAuth metadata (GET /.well-known/oauth-authorization-server) built issuer and the endpoint URLs from the APP_URL variable, which the deployment does not set for the backend, with a http://localhost:3000 fallback. With that variable unset the document advertised an address no client can reach.

The welcome page at GET /v1/me had a different cause with the same outcome: it built every URL from the instance domain at once — both the images and the "Documentation" / "Home" buttons. On a stand those buttons led to the production dashboard.

After

OAuth metadata resolves through a shared helper that refuses a loopback value in production and falls back to the instance public domain.

The welcome page now keeps two addresses apart: images still load from the instance domain (otherwise they would not open), while everything clickable leads to the dashboard of the stand the page was opened from.

2026-08-22

NEW-0822-1: promo code on an occupied seat: the preview returns branches and redemption executes them

Before

POST /v1/cowork/coupon/preview answered only what the code grants, and on an occupied seat redemption refused with "the seat is already paid" — with nothing the person could do about it.

After

The preview returns a decision field — what this code does to the seat and what may be offered: apply, extend (same tier, the paid window moves), choose (branches to pick from, where "apply now" carries losesDays — the whole days of paid term that burn) or refuse with a refusal code. The chosen branch goes to POST /v1/cowork/coupon/redeem in the new optional field action (apply | extend | force | resume-and-apply); omitting it keeps the previous behaviour.

The action is re-checked at redemption time: if the seat changed meanwhile, the answer is 409 COUPON_ACTION_NOT_AVAILABLE and the code is NOT spent. The correct reaction is to re-read the preview and offer the branches it returns now. An unknown action value answers 400 INVALID_ACTION — such a body previously answered 400 INVALID_CODE, pointing at the code field, which was not the problem.

BC-0822-2: the create and rotate responses now match the documented key shape

Old format supported until: not provided

Before

On some accounts POST /v1/keys and POST /v1/keys/:id/rotate returned the whole key row with only the secret fields removed. Alongside the documented shape, the response carried internal platform fields that appear neither in the key-shape reference nor in GET /v1/keys and GET /v1/keys/:id: preMigrationScopes, ownerActive, deletedAt, isOAuthApp, appId, purpose, scopesAuthoritative, linkedServerId, userAgentAutoModel, webhookScopesRepairedAt, tokenExpiresAt.

After

Both methods return exactly the documented key shape — the same field set as GET /v1/keys/:id, plus the one-time rawKey. The internal fields listed above are gone from the response; none of them was documented or part of the contract.

If your integration read any of them, switch the source: key state is status, access mode is accessMode, and the issuing channel is issuedVia. Documented fields, expiry and error codes are unchanged.

BC-0822-3: key rotation now requires the same Bitrix24 plan as creation

Old format supported until: not provided

Before

On an account whose Bitrix24 plan does not grant access to the platform, POST /v1/keys/:id/rotate issued a new key, while POST /v1/keys on the same account answered with a plan-required refusal. Rotation stayed a way around that requirement.

After

Both methods answer the same way. On an account whose plan does not grant access, rotation returns 403 with the same code as creation, INT_TARIFF_REQUIRED.

Only accounts without a qualifying plan are affected. Self-hosted accounts, accounts on a qualifying plan and already-issued keys are unchanged: nothing is revoked or stopped, and rotation resumes as soon as the account is on a qualifying plan.

NEW-0822-4: a key now reports the channel it was issued through, and a refusal reports its exact cause

Before

POST /v1/keys and POST /v1/keys/:id/rotate did not report which channel issued the key on the account. On accounts where only the platform module can create an inbound webhook, both methods answered with an issuance error even though issuance on the account itself worked.

After

The key shape carries an optional issuedVia field — the issuing channel; it arrives in the responses of POST /v1/keys, POST /v1/keys/:id/rotate, GET /v1/keys, GET /v1/keys/:id and PATCH /v1/keys/:id. A refusal body gained an optional error.reason field with the exact cause, while error.code on existing refusals is unchanged. Accounts where the platform module issues keys are now served by both methods.

The create and rotate responses are now identical regardless of the issuing channel — some channels used to return a narrower field set. The message field stays human-readable and may change: branch on error.code, not on its text.

FIX-0822-5: a rotation refused over scopes now reports the same code on every account

Before

POST /v1/keys/:id/rotate on a key left with only application-context scopes — placement, entity, userfieldtype — answered differently depending on the channel the account issues keys through. Where the platform module issues the key, 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID arrived, while other accounts got a generic 502 BITRIX_UNAVAILABLE after a failed issuance attempt.

After

The scope set is checked before the account is contacted, so the refusal is the same everywhere — 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID, the code creation and update already return. Nothing changes on the client side: the refusal is more precise and arrives earlier. To let rotation through, add a data scope to the previous key via PATCH /v1/keys/:id.

NEW-0822-6: platform requests to Bitrix24 now carry a signed origin proof

Before

The portal refused the call on plan grounds or for a missing Market subscription, and a platform request looked to it exactly like any other integration.

After

Every Bitrix24 request carries an X-Vibecode-Origin header — a short-lived signed token. The token names the origin: cowork for a paid Cowork/Code seat key, app for every other user key, vibecode for the platform's own service calls. A portal with the Vibecode connector module installed admits Cowork/Code requests on that proof; other values grant nothing. Portals without the module ignore the header; existing integrations are unaffected.

FIX-0822-7: Reliable source downloads for dedicated VM deploys

Before: a dedicated virtual machine fetched source.url through its own network path. One orchestrator retry did not tolerate intermittent egress or NAT failures, and callers received raw agent networking text.

After: for servers enrolled in the staged rollout, the platform downloads the archive and streams it to the VM through the tunnel, with up to four attempts and backoff inside a shared five-minute budget. The compatible VM-download fallback and public /upload receive bounded retries, a safe outbound policy, and stable messages under the same rollout; before enrollment, the existing contract is preserved. DEPLOY_FAILED is unchanged; in the new mode a failed download step adds causeCode, retryable, and attempts. See the deploy documentation.

Impact: request payloads do not change. Automation can branch on the new fields instead of parsing message text; archives up to 500 MB are streamed and do not consume an inline-memory slot. For public /upload, the long phase in the new URL mode completes under an HTTP 200 keepalive response, so determine success or failure from JSON success and error.code; pre-dispatch checks and pre-enrollment behavior retain their previous HTTP statuses.

BC-0822-8: rotating and bringing back platform-issued keys is closed

Old format supported until: not provided

Before

POST /v1/keys/:id/rotate rotated any key of its owner, and PATCH /v1/keys/:id moved any key back to ACTIVE and pushed its expiry back — including the keys the platform issues on its own separate endpoints: a Cowork/Code desktop key, an agent key and a project deploy key. In the GET /v1/keys listing such a key is barely distinguishable from a personal one, so a "rotate or switch back on all my keys" script walked over it along with the rest: rotation answered 201 with a fresh rawKey, switching back on answered 200 — and the key value never changed there, so the previous one started working again.

After

Both operations on such a key answer 403: rotation with the code SYSTEM_KEY_ROTATE_FORBIDDEN, moving back to ACTIVE and extending the expiry with the code SYSTEM_KEY_REACTIVATE_FORBIDDEN. The response text says where a key of that class is issued again. The key is left as it was in both cases. Both operations bypassed the checks that guard the issuance of each such key: for keys carrying vibe:cowork — Cowork/Code access, the account "third-party clients" policy and the subscription state; for a project deploy key — three platform switches, the Cowork/Code key requirement and an active subscription. Rotation also handed out a value with no expiry at all: on a project deploy key that removed the seven-day lifetime, the only thing that limits a leaked key. Revoking a key and shortening its expiry are still allowed: those stop a key rather than hand one out. The former behaviour is gone at once, with no transition period.

What integrators should do

Exclude the keys the platform issues from bulk rotation and bulk switch-on: a Cowork/Code desktop key, an agent key and a project deploy key. The first two are recognisable in the GET /v1/keys response by the vibe:cowork scope; a project deploy key has no separate marker in the listing, so treat a 403 with these codes as the final answer for that key and do not retry. A desktop key is issued again by connecting the Cowork/Code desktop app, an agent key — by re-issuing the agent key in the Vibecode dashboard, a project deploy key — by calling POST /v1/cowork/deploy-key again. Other keys rotate and switch back on as before.

NEW-0822-9: POST /v1/cowork/deploy-key is closed to external-agent keys

Before

The endpoint checked the vibe:cowork scope only.

After

On POST /v1/cowork/deploy-key a key issued for a third-party agent gets 403 COWORK_HARNESS_KEY_FORBIDDEN. Such a key lives inside someone else's application, while minting a project deploy key revokes the previous one and moves the owner's servers and applications onto the new key. Desktop and agent keys are unaffected.

NEW-0822-10: Reactivating a subscription key checks the issuance gates

Before

A subscription-billed key went back to active through an ordinary status field change, and its expiry was cleared with null. Only the permanent block was checked, so a revocation by the Bitrix24 account administrator was undone in a single request — and the secret itself never changed.

After

PATCH /v1/keys/:id answers 403 with the matching gate code when the request moves a subscription key to ACTIVE, or pushes back or clears expiresAt, while Cowork access, the Bitrix24 "third-party clients" policy or the subscription state is closed. Shortening the expiry, revoking and editing the other fields work as before. Ordinary keys are unaffected.

NEW-0822-11: Rotating a subscription key checks the issuance gates

Before

Rotation carried the key's scopes and purpose over verbatim, asking nothing.

After

POST /v1/keys/:id/rotate answers 403 with the matching gate code when rotating a subscription-billed key while Cowork access, the portal "third-party clients" policy or the subscription state is closed. Ordinary keys rotate as before.

NEW-0822-12: POST /v1/keys rejects subscription billing

Before

The billing field did not exist in the request body; the unknown key was silently dropped by the schema.

After

On POST /v1/keys the value billing: "subscription" is rejected with BILLING_MODE_NOT_SUPPORTED. Subscription-billed keys are issued from the Vibecode dashboard only — that is where the access, Bitrix24 account policy and subscription-state checks live, and the public route has none of them. billing: "wallet" and requests without the field behave exactly as before.

FIX-0822-13: The inactive-subscription refusal now points at the subscription page

Before

The 402 refusal carrying code cowork_subscription_inactive advised activating the subscription by calling POST /api/cowork/subscription. That route works only inside a signed-in web session and is unavailable to a client authenticating with an API key. A third-party agent client shows the message field verbatim, so the advice looked actionable while there was nothing to act on.

After

The same refusal on POST /v1/chat/completions names the state and the place where it changes: the subscription is resumed in the Cowork/Code section of your Vibecode account, and the key stays the same. The code, the status and the other body fields are unchanged.

2026-08-21

FIX-0821-1: iblockTypeId=structure is accepted on /v1/lists

Before

iblockTypeId accepted only lists, lists_socnet, and bitrix_processes. The value structure (the absence-calendar infoblock type) returned 400 INVALID_IBLOCK_TYPE, even though GET /v1/lists/:iblockId/type returned it.

After

structure is in the allowed set on every /v1/lists route. The Bitrix24 response for that type (data or 422/403) is no longer replaced by our 400. Other unknown types still return 400 INVALID_IBLOCK_TYPE. The default is unchanged: lists.

Impact on integrations

Requests to structure infoblocks, including the stock absence calendar, now reach Bitrix24. Existing integrations that use other types require no changes.

FIX-0821-2: currencyId and explicit selection of non-returned fields

Before

POST /v1/products and PATCH /v1/products/:id accepted the currency only under the currency name. An explicit selection of a field marked notReturned: true was accepted without a warning even though the response contained no value.

After

Product write methods accept currencyId as an additional name for currency. If both names are present, currency wins, and responses still carry only currency. The additional name is marked writeOnly and notReturned in /fields, /v1/guide, and OpenAPI. Explicitly selecting any non-returned canonical name now adds an UNKNOWN_SELECT_FIELD warning: products.currencyId, tasks.realStatus, product-sections.sort, bank-details.entityTypeId, telephony-lines.serverName, bizproc-templates.templateData, and catalog-products.iblockSection. The native Bitrix24 name select=CURRENCY_ID continues to select the readable products.currency field. Each name is covered by the field references for products, tasks, product sections, bank details, telephony lines, business process templates, and catalog products. Currency filtering remains unsupported and returns 400 UNSUPPORTED_FILTER.

Impact on integrators

Read requests still return 200 and the other selected fields, but now carry a warning. Remove non-returned names from select: use currency for the product currency and status for the task's actual status.

FIX-0821-3: product description filter is no longer rejected

Before

GET /v1/products with filter[description] and POST /v1/products/search with the same filter returned 400 UNSUPPORTED_FILTER, even though the description was stored when the product was created.

After

Exact match and $in on description are accepted the same way as on name. Operators, including $contains, still return 400. The price and currency filters are unchanged.

FIX-0821-4: the refusal on creating an employee without a department now names the field to pass

Before

POST /v1/users without departmentId on an account with the extranet module installed answered 422 with the text no_extranet_field. No field of that name exists in the request body or in the GET /v1/users/fields output, and nothing in the response pointed at the department — the refusal gave no way to tell what to correct. The employee was not created.

After

The response now carries a hint: it names the field in both spellings — UF_DEPARTMENT for a direct call and departmentId for the POST /v1/users wrapper (both are accepted) — points at GET /v1/departments as the source of values, gives the root department as a working example, and mentions POST /v1/users/invite, which supplies the department itself. For an external user the alternative is named — EXTRANET together with SONET_GROUP_ID instead of a department. The departmentId description in the field reference now states the requirement too, so the condition is visible before the request is sent.

What integrators should do

No action is required: the status code and the envelope shape are unchanged, only the hint was added. The departmentId field is deliberately not marked mandatory on the Vibecode API side — an account without the extranet module accepts a create with no department, and a hard requirement would break those requests.

NEW-0821-5: Open Channels dialog metadata via the API

A new endpoint POST /v1/openlines/dialogs/lookup — a wrapper over the Bitrix24 method imopenlines.dialog.get. It returns the card of a single Open Channels dialog (name, type, line, message count, dates) by one of the identifiers: chatId, dialogId or sessionId. It does not return the message history. Requires the imopenlines scope.

The response carries a derived lineId field — the line identifier parsed from the dialog binding; it is the entry point to GET /v1/openline-configs/:id. Lookup by sessionId resolves a dialog straight from a session identifier taken from the id field of POST /v1/openlines/sessions/search.

BC-0821-6: a structured value in a scalar field is refused instead of silently lost

Old format supported until: not provided

Before

An entity write accepted an object or an array in a field declared scalar and answered with success. POST /v1/deals carrying {"title": {"a": 1}} returned 201 while the deal card showed the string Array — that is how Bitrix24 casts an array to a string. The value could not be recovered and the client saw no error.

After

Such a request is refused before the Bitrix24 call — 400 with code INVALID_PARAMS and the field name. The rule covers fields declared string, number, boolean, date and datetime, on entity writes under /v1/<entity>: create and update, POST /v1/batch, per-entity batch write and import.

What did NOT change: a number or a boolean in a string field is still accepted (Bitrix24 stores 123456 and 1, so nothing is lost), null is still accepted, and fields declared object, array or multi-value accepted structures before and still do.

Impact on integrators

Review any code that builds a write body from an external source: where an object or an array reached a scalar field, the request used to succeed while losing the value and will now return 400. Send a scalar value to such a field.

The boundaries are stated explicitly. A name absent from the entity schema (user fields UF_*, propertyNNN, a typo) is not checked — it has no declared type. The refusal shape differs by surface, and so does its reach. The global batch refuses only its own sub-call and puts the failure in data.errors["<id>"] with separate code and message fields. The per-entity batch write and import refuse the whole request: a 400 with code BATCH_ITEM_VALIDATION or IMPORT_ITEM_VALIDATION, with the element index and INVALID_PARAMS inside message. Such a response carries no per-item results, and nothing reaches Bitrix24. A few bespoke write routes are not covered yet — addresses, task comments, document templates, Open Channels config and product rows; there the previous behaviour still applies, and they are closed separately.

FIX-0821-7: PATCH /v1/infra/servers/:id/access-policy now preserves the access list on policy change

Before

Switching PATCH /v1/infra/servers/:id/access-policy away from NAMED_USERS or DEPARTMENT to any other policy permanently deleted the access list (users and departments added via POST /access) — even though the docs promised the records stay in the database and simply stop applying until the policy becomes a named one again.

After

The list is preserved when leaving NAMED_USERS/DEPARTMENT — behavior matches the documentation again.

Impact on integrators

No action required — behavior now matches the already-published documentation.

BC-0821-8: a busy shared galaxy exec channel now answers 409 instead of 502

Old format supported until: not provided

Before

POST /v1/infra/servers/:id/exec for an application in a galaxy (kind: "GALAXY_APP") answered 502 with the EXEC_BUSY code when the host's shared exec channel was busy. The response carried neither a Retry-After header nor the retryable / retryAfter fields, so a machine client read the refusal as a gateway failure and did not retry. The same refusal on POST /v1/infra/servers/:id/deploy already arrived as 409 with a retry signal.

The error.hint in 409 EXEC_BUSY responses on galaxy routes offered to unstick the channel via POST /v1/infra/servers/:id/unstick. That call is not available to an application owner or a host owner by contract — it answers 409 GALAXY_UNSTICK_UNSUPPORTED, because the exec channel is shared by every application on the host.

After

A busy shared host exec channel arrives as 409 with the EXEC_BUSY code, a Retry-After header and the retryable: true / retryAfter (seconds) fields — the same contract as every other "busy" refusal. Other execution failures for an application in a galaxy still arrive with status 502.

Two different states now share the 409 status, and they are machine-distinguishable by the presence of error.hint.autoExpiresInSeconds: the application's own lock carries it (the remaining lock TTL), a busy shared host channel does not. recoveryAction cannot tell them apart: on a galaxy application and on the galaxy host itself that field names no concrete call at all — only "wait" and "retry" — because releasing a lock there can abort a running operation and, on a shared host, the commands of neighbouring applications with it. The machine-actionable advice is therefore the same in both states — wait and retry at the Retry-After interval.

Important: this is said about the galaxy states, not about the /exec route as a whole. On a dedicated virtual machine (kind: "STANDALONE") the recoveryAction of the same 409 still names DELETE /v1/infra/servers/:id/lock, unconditionally — and against a running deploy that call removes the per-server serialization the deploy relies on. So recoveryAction must never be executed without reading error.hint.recovery first, in any state. The lock-release address stays in error.hint.recovery, with the server identifier substituted, the owning key required and the caveat that it is only for when you have confirmed nothing is running.

Reading the log answers by the same contract now. GET /v1/infra/servers/:id/logs for an application in a galaxy goes through that same shared host exec channel, and with the channel busy it used to answer 200 with an empty logs list — claiming the application had no output. The busy state now arrives as 409 with Retry-After, and other read failures as 502 carrying the agent's code.

What integrators should do

A client that branched on the HTTP status and treated 502 on /exec as a terminal failure must stop doing so: the busy state now arrives as 409 and should be retried at the Retry-After interval. A client that read error.code needs no change. If your flow called POST /v1/infra/servers/:id/unstick because the platform suggested it, that call never worked on galaxy servers — replace it with a retry, and contact support if the refusal persists. If you branch between the two 409 states of /exec in code, key on the presence of error.hint.autoExpiresInSeconds rather than on the text of recoveryAction.

BC-0821-9: the per-entity batch now explains what it did with select

Old format supported until: not provided

Before

POST /v1/{entity}/batch with the list action applied select to the response but said nothing about what it dropped. A name the entity does not have simply vanished: the record came back narrowed and no explanation existed anywhere — no error, no warning. The single list and the global batch both report such a name as a warning; this door was the only one where field selection was completely silent.

After

The sub-call carries its own meta.warnings with the UNKNOWN_SELECT_FIELD code and the field name — the same shape the single list uses. The warning belongs to ITS sub-call: neighbouring items get no meta of their own, and the key never arrives as an empty array — nothing to say means no key.

Entities where an unknown name answers with an error (today, calendar events) now refuse such a sub-call here too — UNKNOWN_SELECT_FIELD before the Bitrix24 call. The refusal is per-call, as in the global batch: only that item fails, the other forty-nine still run. Before, the hard selection guard did not fire on this door at all.

The value * still means "return every field": no selection is applied and an unknown name next to it refuses nothing. A warning still arrives: a select of *,titel returns every field AND says the second name means nothing — exactly as on the single list and in the global batch.

Impact on integrators

The additive half breaks nothing: meta is a new optional key next to data and total. The breaking half is the hard selection: a sub-call that used to answer with a narrowed record and code 200 now answers with an error in its slot on calendar events. There is deliberately no support window: the previous behaviour was itself the defect — the requested name vanished silently, with nothing to tell that apart from "the field is not in the record". Review handlers that treated the absence of an error as proof that every select name was recognised.

NEW-0821-10: Open Channels session transcript via the API

A new endpoint POST /v1/openlines/sessions/history — a wrapper over the Bitrix24 method imopenlines.session.history.get. It returns the message history of a chat's latest Open Channels session by the chat identifier: messages, participants and file metadata in one response. Requires the imopenlines scope.

Input is by the chat identifier only (chatId, the chat2043 form is accepted too). By it the latest session of the chat is taken. The method has no pagination — the transcript comes in full. For page-by-page reading of messages use GET /v1/chats/:dialogId/messages.

The endpoint is enabled gradually by the Vibecode platform: while it is off, the call answers 403 OPENLINES_HISTORY_DISABLED — a sign the capability is not active yet, not an integration error.

NEW-0821-11: galaxy app multipart deploy stores the archive in source storage

The multipart deploy of a galaxy app no longer buffers the whole archive in platform memory: where multipart depositing is enabled, the archive is stored as a version in the source storage and reaches the host through a signed link. Where the host is allowed to fetch the archive itself, a recognised tar.gz is downloaded by the host — verifying the size and checksum recorded for that version — and a failed fetch then arrives as a separate UPLOAD_DOWNLOAD_FAILED / UPLOAD_EXTRACT_FAILED / UPLOAD_NO_SPACE code in the buildLog tail; a zip and an unrecognised format keep the previous path, through the agent. The size limit on an archive sent in the request body is unchanged — the body still travels through the platform. The version stays in the depot even when the deploy fails: it is listed among the versions and can be redeployed by source.versionId.

2026-08-20

NEW-0820-1: the Cowork subscription snapshot is described in the API specification

Before

GET /v1/cowork/me worked and was listed in the /v1/guide directory, but the V1 specification did not carry it. You could not generate a client from the spec or verify the response shape — reading the directory by eye was the only option.

After

The operation is described: tier and subscription state, the three quota windows as integer percentages with their reset time, and the next charge date. It also states that the successful body is the object itself, with no success wrapper, while errors arrive in the usual { success: false, error: { code, message } } envelope. The offPeak and relief blocks are described as absent when the feature is disabled: check for the presence of the key rather than comparing the value with null.

FIX-0820-2: `include` examples use relation names

Before

OpenAPI and MCP showed plural related-entity names for the include parameter, causing requests to fail with INVALID_INCLUDE.

After

Examples use the actual relation names contact,company.

FIX-0820-3: MCP now forwards timeline log action parameters correctly

Before

The manage_timeline_log tool accepted only string id values, omitted the request body for pin and unpin, and omitted query parameters for get_note and delete_note.

After

The tool accepts string or numeric id values and forwards the required parameters for these actions to /v1/timeline-logs/*. The delete description now states that personal keys cannot delete these entries: deletion is available only to the same OAuth application that created the entry.

NEW-0820-4: calendar sections now expose schema and search routes

Before

calendar-sections had no GET /v1/calendar-sections/fields or POST /v1/calendar-sections/search, so agents could not discover fields and valid calendar types in advance or use the standard search surface.

After

GET /v1/calendar-sections/fields returns the static schema with required fields and the user, group, company_calendar, and location types. POST /v1/calendar-sections/search accepts owner context through filter.type and filter.ownerId; additional filters are explicitly rejected because the Bitrix24 method does not support them.

FIX-0820-5: personal keys report only executable scopes

Before

GET /v1/me could report the placement, entity, and userfieldtype scopes for a personal key even though these features require an OAuth application context. Key creation and update also accepted userfieldtype as a regular scope.

After

GET /v1/me, personal-key creation, and personal-key update exclude placement, entity, and userfieldtype. The userfieldconfig scope remains available. OAuth application keys are unchanged.

Impact on integrations

No action is required. Use an OAuth application key for placements and custom user field types.

FIX-0820-6: the tasks permission now works on every task operation, no matter how the key was issued

Before

A key holding the tasks permission was refused on some task operations — which ones depended on how the portal had issued the key's webhook. Bitrix24 accepts two spellings of the same tasks permission (task and tasks), and they open different groups of operations: older task operations require the first spelling, newer ones the second. A key kept the spelling its owner had picked, and on some issuing paths only that one spelling reached the portal. Inside POST /v1/batch such a refusal arrived within a 200 response, on the sub-command rather than the whole request.

After

The tasks permission is registered on the portal in both spellings regardless of the issuing path, so all task operations are available. Keys issued earlier reach the same state when their webhook is reconnected. The key's own permission list and the GET /v1/me response are unchanged — no client action is required.

FIX-0820-7: bot chat creation returns the identifier the other actions accept

Before

After creating a chat, the manage_bot_chat tool put a numeric identifier in the most visible places — data.chat.id and data.recentConfig.chatId. Reusing that number in the next action — GET /v1/bots/:botId/chats/:dialogId, leaving the chat, transferring ownership — returned a BITRIX_ERROR "chat does not exist": for Bitrix24 a bare number in dialogId means the personal dialog with the user of that id, not the group chat with that id. The usable identifier, such as chat471, sat deeper in data.chat.dialogId, and the tool description did not name that format.

After

The chat creation response starts with a chatId field holding a value such as chat471, and that is the value the other actions of the tool accept. The Bitrix24 fields data.chat.id and data.recentConfig.chatId are unchanged and stay numeric. The description of the chatId parameter now names both formats: chatN for a group chat, a bare number for the personal dialog with that user.

Impact on integrations

MCP callers need to do nothing. The POST /v1/bots/:botId/chats response is unchanged for REST: there you still have to take chat.dialogId rather than the numeric chat.id. GET /v1/bots/:botId/chats/:dialogId and the other actions still accept both chatN and a number as a personal dialog identifier.

FIX-0820-8: AI provider refusal: a readable message instead of relayed prose, and one error shape for streaming and non-streaming

Before

When the AI provider refused the platform's request, POST /v1/chat/completions, POST /v1/embeddings and POST /v1/audio/transcriptions answered 502 ai_provider_unavailable and put the provider's own wording into error.message verbatim. The provider could report a failure of its own infrastructure as an authorization error — so the response spoke about authorization where neither the caller's API key nor the caller's network was involved, and the caller went auditing both.

Streaming (stream: true) returned the same failure in a different shape than a plain request: code arrived in upper case instead of lower case, there was no type field at all, and retryAfter and retryable were reserved for a stalled stream and for overload. A client branching on error.type or on retryable could not tell a temporary refusal from a final one, and had nothing to wait on.

After

The wording now depends on who owns the credential the provider refused. A key the caller connected themselves (BYOK) — the provider's message passes through as before: it is addressed to the key owner and tells them what to do. An account-level credential — the response names the object and the person who can update it, and states plainly that retrying will not help. A platform credential — the response says the caller's API key and network are not the cause. The 502 status, the ai_provider_unavailable code and the providerStatusCode field are unchanged in every case.

The streaming error took the same shape as the non-streaming one: code in lower case, type present, and every frame carrying a retryAfter pause now carries retryable: true as well. Both fields appeared for a temporarily unavailable provider, for rate limiting and for the cooldown after a run of failing calls — previously only a stalled stream had them.

The retry hints now agree with the wording of the response: a refusal a retry cannot fix carries neither the pause nor the flag. That covers a refusal of the request body itself (ai_provider_rejected) and a provider-refused account credential or the caller's own key, where the response states outright that the credential has to be updated. A temporarily unavailable provider stays retryable.

FIX-0820-9: an attachment whose extension does not match its content is no longer rejected

Before

POST /v1/feedback/attachments compared the type declared by the client with the file's own signature and answered 400 MIME_MISMATCH when they differed. The client derives that type from the extension, so a JPEG saved as image.png arrived as image/png and was rejected — even though both formats are allowed and the file was intact.

After

Processing is driven by the file's actual format. A mismatch between two allowed formats (PNG, JPEG, WebP, GIF) is accepted, the file is re-encoded from its content, and its mime in the response is the result of that re-encode, as before. MIME_MISMATCH is left for the single case where the file's signature is not recognized at all.

FIX-0820-10: MCP now preserves one chat identifier format

Before

The manage_chat.add_users action passed a value such as chat457 to a numeric backend route without normalization, so Bitrix24 reported an empty chat ID. A chat created through the tool could not be left through the same MCP tool, and find looked like text search.

After

add_users and the new leave action accept the standard chatN dialogId value and pass a numeric ID to the route. add_users preserves its legacy positive numeric chat ID for compatibility, while the new irreversible leave action requires an unambiguous chatN; the caller must convert a numeric ID returned by chat creation to chatN before calling leave. A missing or invalid ID is rejected before any network call. The tool warns that an owner must transfer chat ownership first using the numeric ID without the chat prefix. The find description now names the required entityType and entityId parameters for a CRM-linked chat lookup.

FIX-0820-11: addresses now apply select — records narrow, and an unknown name is no longer lost

Before

The select parameter is documented for every entity, but on addresses it did nothing at all. List, search and get-by-composite-key answered with the full record no matter how many names the caller listed, and an unknown name disappeared without a trace — no error, no warning. This was the only entity where field selection was completely silent.

After

All three address doors apply select the way every other entity does: only the listed fields stay in the records, canonical names and native Bitrix24 names are both accepted (CITY projects city), and * still means "return every field".

An unknown name behaves differently from door to door. Get-by-composite-key picks the fields on the Vibecode side, so a name absent from the schema arrives as an UNKNOWN_SELECT_FIELD warning in meta.warnings while the record itself comes back — that door gains a meta block only when there is something to warn about. List and search pass the listed names on to Bitrix24, so the account decides the outcome there: one that has no such field rejects the whole call — the answer is 422 BITRIX_ERROR, the name is quoted in the message, and no data arrives.

The composite address key — typeId, entityTypeId, entityId — always comes back, even when the select does not list it. On most entities a single id field plays that role: it is what tells one record from its neighbour and what the update and delete addresses are built from. On addresses all three fields carry that role together.

Separately: the name id in select follows the same split. On get-by-composite-key it is no longer treated as a typo — addresses have no id of their own, so select=id,city used to return a warning about the id field, and that request now reads as "tell me which record this is" and returns the composite key. On list and search the name id goes to Bitrix24 and is subject to that same account check.

Field selection stopped stripping the route key on smart processes and telephony lines

On most entities the operation address is built from id, and select=id,… worked as expected. But there are two where the route key is named differently, and field selection threw it away: on smart processes it is entityTypeId, on telephony lines (/v1/telephony-lines) it is number. Both fields now stay in the response even when the select does not list them: GET /v1/telephony-lines?select=name returns {name, number} instead of {name}.

On smart processes this removes a trap: the record also carries an internal id field that takes no part in operation addresses — field selection used to keep exactly that one, and an address built from it led to a different record.

On every other entity the rule is unchanged and worth remembering: if you list fields in select, list id too — the Bitrix24 methods that honour the selection (deals, contacts, companies, leads, quotes, smart process items) return exactly what was asked for, and an unrequested id will not be in the response.

Impact on integrators

Nothing to change if you never passed select to addresses — the response is the same as before. A call that passed select and relied on getting the full record back will now receive only the requested fields: that is the documented behaviour of the parameter, brought in line with every other entity. Check field names against GET /v1/addresses/fields.

BC-0820-12: a caller-supplied bot token is validated for length and alphabet

Old format supported until: not provided

Before

PATCH /v1/bots/:botId accepted any fields.botToken value — say support-bot-2026. The call answered 200 and the portal took the new token. There were no length or shape checks: Bitrix24 applies its 40-char cap when a bot is registered and when it is switched to webhook mode, but not on a plain update.

After

A caller-supplied token is validated before the portal call: 32 to 40 chars from the [A-Za-z0-9_-] alphabet. Any value present in the request that does not fit that bound — too short, empty, carrying stray characters, or not a string at all — is rejected with 400 and code BOT_TOKEN_INVALID; the portal is not called and the bot token stays as it was. The bound is the same one used at bot registration, and its lower edge matches the length of the token the platform issues itself.

The reason is that this very token authenticates the events delivered to the bot at POST /api/bot/webhook: a short or guessable token would let anyone forge a bot event without any authentication.

What integrators should do

If you supply the token yourself, use a random value of 32 chars or more (32 hex chars, for instance) from the [A-Za-z0-9_-] alphabet. If you do not supply one, there is nothing to do: the platform issues the token and it passes the bound. There is deliberately no support window for the old behaviour — a weak token already left the bot inoperable, because the platform never stored such a value on its side.

FIX-0820-13: bot events delivered by webhook without a portal address are no longer lost

Before

The POST /api/bot/webhook receiver identified a bot by the pair "portal + bot number": the bot number is a per-portal sequence rather than a global identifier, so the portal had to be resolved from auth.domain or auth.member_id in the request body. For a bot registered through an incoming webhook neither field is reliable: the portal address does not arrive in every envelope, and member_id only resolves for portals whose id the platform already knows. An event without a portal address was rejected with 403 AUTH_FAILED, and imbot webhooks are never re-sent: the user's message was lost for good, and from the platform side it looked as if nobody had written to the bot at all.

After

The bot is identified by the top-level auth.application_token — for a webhook-registered bot that value points at one specific bot on its own, so the portal is no longer needed for it. The former domain-based path is kept and behaves as before: it serves registrations whose token arrives in a different shape. Token verification is not weakened — the comparison stays constant-time, and an event carrying another bot's number in the body is still rejected.

The receiver's rejections also got their own codes — BOT_WEBHOOK_AUTH_FAILED, BOT_WEBHOOK_ID_MISMATCH, BOT_WEBHOOK_INVALID_BOT_ID, BOT_WEBHOOK_BOT_DISABLED — so lost events show up in the rejection statistics instead of only in the logs.

One more change in PATCH /v1/bots/:botId

A token supplied by the caller in fields.botToken is now stored on the platform side as well. Previously it only reached Bitrix24 while the platform kept the old value, leaving the bot silently inoperable in both directions: outgoing calls got 401 and inbound events were rejected.

Impact on integrations

No action required. The receiver's HTTP status codes are unchanged (403 / 400 / 410), and the error field in the body stays as it was, with a code field added next to it. Bots whose events used to be rejected start receiving them without re-registration and without a token change.

FIX-0820-14: the portal receives Bitrix24 scopes only, and a platform-only key no longer gains a webhook on rotate

Before

When a webhook was issued, the portal received not just Bitrix24 scopes but Vibe platform scopes as well — vibe:infra, vibe:ai, vibe:search, vibe:storage. Bitrix24 does not know such scopes and silently ignored them, so the key's real permissions were unaffected, but the set on the wire differed per issuing path: the dashboard sent one thing, POST /v1/keys another, the self-hosted channel a third.

The same divergence had a visible effect on secret rotation. A key whose scope set holds platform scopes only gets no webhook on the portal — there is nothing to register. Yet rotating such a key sent the portal a set of platform scopes alone and got a webhook back that the key did not have before: b24Ready flipped from false to true even though the key still could not call Bitrix24.

After

The portal receives Bitrix24's own scopes only, identically on every issuing channel. When no Bitrix24 scope remains, no webhook is requested at all: the key stays platform-only and b24Ready stays false on create and on rotate alike.

Impact on integrations

The response shape, the error codes and the key's stored scope set are unchanged: vibe:* still appear in scopes and still open the platform sections /v1/ai, /v1/search, /v1/storage, /v1/infra. No action is required. The only visible difference is for anyone who rotated a key holding no Bitrix24 scope and expected b24Ready: true — such a key now honestly answers false, exactly as it does on creation.

FIX-0820-15: on the international segment the tariff refusal names a Vibe+ plan

Before

An account on a free Bitrix24 plan received the INT_TARIFF_REQUIRED refusal whose userMessage named a paid Bitrix24 plan as the access condition. The pricing page, meanwhile, states that full access to the Vibecode platform is unlocked by a plan of the Vibe+ line — the customer read two different conditions inside one product.

After

On the international segment the userMessage of this code names a Vibe+ plan, the same condition the pricing page sells. Every surface of the code is covered: the refusal body on infrastructure creation and wake, the capabilities.servers.create slot in GET /v1/me, the gateway interstitial and the key-issuance toast.

The machine field details.requiredTariffs is unchanged: it still lists the tariffs that clear the refusal. Build the purchase advice from that field and use the human-readable string to explain the reason. The refusal code, its HTTP status and the envelope shape are unchanged.

Kazakhstan and Uzbekistan accounts, self-hosted accounts and the Russian segment keep the previous copy — the Vibe+ line is not sold there.

NEW-0820-16: assigned promo code — the code works only for its recipient

Before

A promo code was redeemed by any portal employee who happened to have it. A workshop batch was handed out by name, but the platform did not know the recipient: a forwarded code worked for whoever entered it first.

Now

A code can be issued to a specific email. Such a code is checked against the Vibecode account email: on a mismatch POST /v1/cowork/coupon/redeem answers 409 with COUPON_NOT_ASSIGNED_TO_YOU, and the code itself stays unspent and still available to its recipient. The POST /v1/cowork/coupon/preview check returns the same code in the reason field.

Codes without a recipient behave as before — any portal employee can redeem them.

NEW-0820-17: blocking a leaked key now reports whether its access links were revoked

POST /v1/platform/keys/revoke-leaked now revokes the access links the key issued along with the key itself, and the response carries a new tokensRevoked field. The key is always blocked; tokensRevoked: false means the key itself is already dead while its links are still alive — the revocation did not go through because of a transient database failure. Repeat the same call: it is idempotent and finishes the job.

FIX-0820-18: revoking a key now closes the access links it issued

Before

PATCH /v1/keys/:id with status REVOKED disabled the key itself but left the access tokens it had issued untouched: share links and bearer tokens kept working until their own expiry, which reaches ten years. An owner revoked a key and believed access was closed, while the links stayed alive.

After

Revoking a key now revokes the access tokens it issued and drops them at the gateway. This matches key deletion, where it always worked that way, and behaves identically on both surfaces — through the API and through the dashboard. Links issued by keys revoked BEFORE this release are closed too: a one-off data fix retires them, not just the new behaviour. Other key changes (name, rate limit, access mode) still leave tokens alone.

2026-08-19

FIX-0819-1: bot message sending accepts top-level dialogId

Before

When sending a bot message through MCP, top-level dialogId was not included in the POST /v1/bots/:botId/messages request, while a request without a recipient returned a platform error.

After

Top-level dialogId is forwarded as the canonical recipient, while the previous body.dialogId remains a compatible fallback. A request without a non-empty dialogId string returns MISSING_PARAMS before sending the message.

FIX-0819-2: the `X-Tariff-Checked-At` header is sent only after a successful plan lookup

Before

The timestamp was written after ANY plan lookup attempt against Bitrix24, including a failed one: a portal whose lookup timed out or was rejected for a key without the required scope still received a fresh X-Tariff-Checked-At. Headers gave no way to tell "the plan was read an hour ago" from "an hour ago we tried and failed".

After

The header is sent only when the last lookup actually read the plan. A failed attempt now sends no header at all, so its absence means "there is no reliable lookup", not "this portal was never checked". The X-Tariff-Is-Commercial header is unchanged and arrives as before.

FIX-0819-3: clarified personal-key embedding and handled OAuth without state

Before

GET /v1/me incorrectly claimed that a personal key could not publish an embedded application at all. When Bitrix24 returned an OAuth code without state, /v1/bitrix-handler stayed on the intermediate page.

After

portalEmbedding describes the working POST /v1/apps → OAuth authorization → POST /v1/apps/:id/publish flow and separately warns that a personal key cannot call placements/bind directly and does not itself provide transparent auth. An OAuth callback without state now redirects to a controlled error page without forwarding the code.

FIX-0819-4: money paths now survive a race for the shared portal balance

Before

Under a rare race of concurrent writes to a portal's balance (a Postgres Serializable-transaction conflict, 40001), one of the competing money paths could fail outright and never complete: the payment provider's webhook credit, Bitrix24 events (bonus grant and revoke, package revoke), the real-time web-search charge, Cowork subscription renewal and tier change, and the daily crons (including vibe-package expiry) — every one of them wrote the balance with no retry and failed on the very first concurrent attempt.

After

Each of these paths now survives a serialization conflict: the platform automatically retries the specific money operation until it succeeds (a finite number of attempts, with jitter between them), so a rare overlap of two concurrent operations on the same balance no longer loses money or returns a failure to the caller.

Impact on integrators

No action required. The payment provider's webhook and Bitrix24 events are processed as normal even under contention with another operation on the same balance — this change requires no additional manual retries on the integrator's side.

BC-0819-5: the freshnessWindowMinutes field is no longer returned

Old format supported until: not provided

Before

GET /v1/me returned a freshnessWindowMinutes field set to 10 inside the capabilities.apps.sourceStorage block, and the 409 SNAPSHOT_REQUIRED refusal of POST /v1/apps/:id/publish carried the same field inside hint. The field named the window, in minutes, within which a saved source snapshot counted as usable for publication.

After

The field is present neither in the capability block nor in the refusal hint. It is returned only when publication checks snapshot age, and right now it does not — a snapshot of any age can be published. No explicit null takes its place: the field is simply absent. The rest of the capabilities.apps.sourceStorage block and the other hint fields are unchanged.

What integrators should do

Read freshnessWindowMinutes as an optional field: if your code requires it, coerces it to a number without checking, or drives a re-save timer from it, drop that dependency. Treat the missing field as "snapshot age is not checked". The field returns only if publication starts checking age again, and its value will be meaningful again at that point. The full hint schema — Source storage.

BC-0819-6: publication refuses when the files of the saved source version are gone

Old format supported until: not provided

Before

POST /v1/apps/:id/publish picked a saved source version by its record, without checking whether its files were still there. A version whose files had already been purged from storage or marked for deletion therefore qualified for publication: the request answered 200, the app moved to PUBLISHED, and downloading the published version afterwards answered 410 SOURCE_VERSION_BYTES_PURGED. Sources that did not exist ended up published.

After

Publication does not pick versions without files at all. If the app or the server has no other saved version, the answer is 409 SNAPSHOT_REQUIRED with hint.reason = app_snapshot_missing or server_snapshot_missing: no files means no snapshot. If such a version is passed as an explicit sourceVersionId, the answer is the same 409, and hint.lastSnapshot arrives as null. This change is unrelated to the snapshot-age check and applies at all times.

What integrators should do

Handle a 409 SNAPSHOT_REQUIRED from publication in the case where it previously could not occur — an app whose source files have been purged from storage or marked for deletion. There is one recovery path: save the archive again through POST /v1/apps/:id/sources or POST /v1/infra/servers/:id/sources and retry publication. Retention and file deletion are described in Source storage.

FIX-0819-7: app publication no longer refuses because the saved sources are old

Before

POST /v1/apps/:id/publish answered 409 SNAPSHOT_REQUIRED when the saved source snapshot was older than ten minutes, even if the code itself had not changed. The check measured the time since the last save rather than whether the sources matched, so the usual order — deploy, then authorize the app on the Bitrix24 account, then publish — ran into a refusal: the authorization step is done by a person and easily takes longer than the window. Getting past it meant saving the very same archive again through POST /v1/apps/:id/sources or POST /v1/infra/servers/:id/sources. The refusal hint carried hint.reason set to app_snapshot_stale or server_snapshot_stale.

After

The age of the saved sources no longer limits publication: a snapshot of any age is accepted. A 409 SNAPSHOT_REQUIRED refusal is left only when there is no usable snapshot at all, and then hint.reason holds app_snapshot_missing or server_snapshot_missing. The values app_snapshot_stale and server_snapshot_stale no longer appear in the response — they come back only if publication starts checking snapshot age again.

Impact on integrators

Nothing to change: publication has simply lost one of its reasons to refuse. Re-saving an unchanged archive before publishing is now redundant and can be dropped from the flow. If your code branches on hint.reason, the branches for app_snapshot_stale and server_snapshot_stale stop firing, yet stay valid: the set of values has not changed.

FIX-0819-8: Publishing an app no longer marks the source version as successfully deployed

Before

After a successful publish the platform wrote deploy status success onto the selected source version — regardless of how the deploy of that version ended, or whether there had been one at all. In the version list (GET /v1/infra/servers/:id/sources), in the manifest and in the sources registry, a version from a failed deploy looked successful after publishing, and a hand-saved version received a deploy status it never had.

After

Publishing writes only its own marker — a linkedDeployId of the form publish:<timestamp>. The deployStatus field keeps whatever the deploy made it: success, failed, or empty for versions saved by hand.

Impact on integrators

No action required. If you read deployStatus as "this version is published", that was never its meaning; publication is carried by the published entry in tags and by the publish: prefix in linkedDeployId.

BC-0819-9: promo code on a closed seat: the `COUPON_SEAT_CANCELLED` refusal is gone

Old format supported until: not provided

A promo code now works on a closed seat — that is how a departed customer comes back. Redemption turns on the granted tier from the moment it is applied, the seat becomes active again, and its closing mark is cleared.

As a result the COUPON_SEAT_CANCELLED refusal code disappeared: nothing produces it any more. If your code matches refusal reasons against a list, drop it — that branch is now unreachable.

One refusal on a closed seat remains, under a different code. A seat closed early while its paid term had not expired answers COUPON_SEAT_ALREADY_PAID_LONGER: redemption would overwrite the paid term with the gifted one, and the purchased months would vanish from the row a refund is computed from.

Affected endpoints: POST /v1/cowork/coupon/preview, POST /v1/cowork/coupon/redeem

FIX-0819-10: a promo code no longer eats the paid term of a downgraded seat

Before

When a platform admin downgraded a seat off a prepaid plan, the row kept its paid term (an end date in the future and the price of the purchased month) while no charge was scheduled any more. Redeeming a promo code on such a seat went through: POST /v1/cowork/coupon/redeem answered with success, and the granted gift rewrote the end of the paid term to the length of the gift. The purchased months disappeared from the row the refund is computed from.

After

Such a redemption is refused with COUPON_SEAT_PAID_TERM_ACTIVE, new in the refusal set of POST /v1/cowork/coupon/redeem. The paid term on the seat is left alone, the promo code stays with the person and is redeemed once the term ends. The other refusals of the set and their conditions are unchanged.

BC-0819-11: an unbind the platform could not confirm no longer looks like success

Old format supported until: not provided

Before

POST /v1/apps/{id}/unpublish answered 200 and cleared placements whether or not the platform had removed the bindings on the Bitrix24 account. POST /v1/apps/{id}/publish and PATCH /v1/apps/{id} with a changed placement set answered 200 even when the placements being dropped could not be removed. POST /v1/placements/unbind removed the placement from the application list without waiting for the account to confirm it.

After

Unpublish still answers 200 and moves the application to UNPUBLISHED, but placements now carries the codes it could not remove and warnings explains each one. Publish and PATCH answer 502 with code PLACEMENT_UNBIND_FAILED and the code list in error.placements when removal is unconfirmed; the application is not published and the catalog metadata is not saved. A single-placement unbind answers 502 with code BITRIX_UNAVAILABLE and keeps the placement in the application list.

Separately: POST /v1/apps/{id}/publish and PATCH /v1/apps/{id} started answering 503 with code NETWORK_DEVKEY_REQUIRED when the account is switched to developer-key transport and the application author holds no such key. Neither endpoint used to return that code.

What integrators should do

The capability is rolling out gradually and is enabled per account: before it is enabled on your account all four endpoints behave as before, an unconfirmed removal still looks like success, and the codes PLACEMENT_UNBIND_FAILED and NETWORK_DEVKEY_REQUIRED do not occur at all. The code BITRIX_UNAVAILABLE on unbinding a single placement existed before the rollout too — only its condition changes: once enabled, an unconfirmed removal answers with the same code. Once enabled, read placements in the unpublish response: an empty list means everything was removed. On 502 with code PLACEMENT_UNBIND_FAILED, retry — the listed placements are still on the account. If your flow treated 200 as proof of removal, switch the check to placements being empty. On 503 with code NETWORK_DEVKEY_REQUIRED a retry will not help: ask the application author to reconnect the account.

Affected endpoints: POST /v1/apps/{id}/publish, POST /v1/apps/{id}/unpublish, PATCH /v1/apps/{id}, POST /v1/placements/unbind

NEW-0819-12: a self-hosted portal can start the Marketplace demo

Before

POST /v1/portals/{id}/activate-market-trial and POST /v1/cowork/activate-market-trial always refused a self-hosted portal: 409 TRIAL_ACTIVATION_UNAVAILABLE, with /v1/cowork/state reporting not_cloud as the reason. The Marketplace demo was available to cloud portals only.

After

A self-hosted portal starts the demo through the same endpoints. Eligibility is decided by Bitrix24 from the portal licence, so the refusal reason is now more precise: demo_used when the demo cannot be granted, and not_supported while eligibility has not been read yet. Response shapes and error codes are unchanged.

The capability is rolled out gradually and is off by default.

BC-0819-13: request body parsing for POST /v1/cowork/deploy-key

Old format supported until: not provided

Before

A request with the Content-Type: application/json header and an empty body answered 400. A request with the Content-Type: text/plain header and a non-empty body was accepted.

After

An empty body is accepted with any header: the endpoint does not read the body. A non-empty body of an unknown type answers 415.

What to do

Drop Content-Type: text/plain from the call or send no body at all. The former behaviour is removed at deploy time, there is no support window.

NEW-0819-14: revoking a Cowork/Code device key with the key itself

Before

A device key could only be revoked from the Vibecode dashboard: both sign-out endpoints take session auth, while an application only holds a key. There was nothing for the app to call.

After

DELETE /v1/cowork/key is available. It revokes the presented key — no identifier is passed, so another key cannot be revoked. It requires the vibe:cowork scope and a Cowork/Code desktop-class key, otherwise 403 COWORK_DESKTOP_KEY_REQUIRED; without the scope, 403 INSUFFICIENT_SCOPE. Calling it again with the same secret answers 401 KEY_INACTIVE. The rate is 5 requests per minute per key, over the limit 429 RATE_LIMITED.

The endpoint works on a zero balance and past the daily quota as well: an emergency exit is never locked.

2026-08-18

BC-0818-1: application and source-management contract clarified

Old format supported until: not provided

Before

OpenAPI did not describe the exact success responses, metadata limits, and some error codes for the application source-storage operations. One application's OAuth key could mutate another application and read or mutate the same author's server sources when the server belonged to a different key. The note limit counted UTF-16 code units, so some valid Unicode strings were rejected. An intermediary cache could retain a temporary download URL.

After

The eight-operation contract now describes the actual response schemas, limits, error codes, and access matrix. An OAuth application key can now directly manage only its own application and access sources of a server owned by that same key. When publishing its own application, an explicit sourceServerId may select the same author's server under a personal key, but not a server owned by another OAuth application. The author's personal keys and account-administrator keys retain access. V1 application-operation audit records store the key owner's Vibe UUID rather than the numeric Bitrix24 user ID. The note limit is counted in Unicode code points. Application and server temporary-link responses are marked Cache-Control: private, no-store, and the URL, including its storage path, is explicitly identified as a short-lived bearer credential.

No transition window is provided because an OAuth application key's former access to another key's resources was an access-control defect.

FIX-0818-2: `?refresh=tariff` on a self-hosted portal re-checks its access state at the source

Before

GET /v1/me?refresh=tariff on a self-hosted portal re-checked the plan but returned the portal's access state from the previous snapshot. A change made right before the call stayed invisible until a background check picked it up.

After

The request re-checks that state at the source as well, and the response is built from fresh data. A change made right before the call is visible immediately.

NEW-0818-3: workgroup roster with member roles

A new endpoint GET /v1/workgroups/:groupId/users returns the members of a workgroup together with their role in it. Previously the /v1/workgroups facade exposed only the owner and the member count, so an application that had to tell a head, a moderator and an ordinary member apart could not do so.

Every row carries userId and role. The role field holds the Bitrix24 letter verbatim: A owner, E moderator, K member. An unrecognised letter is passed through rather than mapped onto a known one or dropped, so branch on the values you know and treat anything else as no permission.

The operation takes no pagination parameters and returns the whole roster, so meta.total always equals the number of rows in data. An empty roster is an ordinary answer, and the owner is not necessarily among the rows — read the owner identifier from GET /v1/workgroups/:id. A 404 means the workgroup does not exist or is not visible to the Bitrix24 identity the key acts as, because Bitrix24 refuses both cases identically.

The endpoint returns membership data, not an authorization decision: what it shows depends on the identity behind the key, and portal-administrator status is a separate fact served by GET /v1/users/me. Nested resources are not addressable through POST /v1/batch, so the operation is called on its own path only. Requires the sonet_group scope.

FIX-0818-4: deals: seven fields from GET /v1/deals/fields are now accepted in a filter

Before

GET /v1/deals/fields listed fields the filter would not accept. A POST /v1/deals/search carrying filter[leadId], filter[quoteId], filter[taxValue], filter[originId], filter[originatorId], filter[additionalInfo] or filter[lastActivityBy] was rejected with 400 UNKNOWN_FILTER_FIELD before Bitrix24 was called at all, even though Bitrix24 does accept those fields in a filter. A report selecting deals by their lead could not be built.

After

All seven fields are declared in the deals schema and are accepted in filter — on GET /v1/deals, on POST /v1/deals/search and on POST /v1/deals/aggregate. They were already accepted in select, but with an UNKNOWN_SELECT_FIELD warning; that warning is gone. Sorting by them already worked before this change and is unaffected. Field names in responses are unchanged. The set of groupBy axes is untouched.

Two notes on values. leadId, quoteId, originId, originatorId and additionalInfo are now marked nullable in GET /v1/deals/fields and in OpenAPI: they return null on a deal that was not created from a lead, from a quote or by import. They were absent from the specification before, so a client generated from it must be ready for null. And on the three string fields (originId, originatorId, additionalInfo) an empty string from Bitrix24 is normalised to null, exactly as it already is on every other string field of the API. Across a 300-deal sample no empty string occurred at all — Bitrix24 returns null on these fields — so no change on real data is expected; but if your code compares such a field with "", compare it against an empty value instead.

Six fields — utmSource, utmMedium, utmCampaign, utmContent, utmTerm and contacts — stay rejected in filter and sort, because Bitrix24 does not support them there. The rejection is deliberate: accepting them would produce a silently wrong selection. The reason is now visible up front, in the description of each field in GET /v1/deals/fields. To filter by contact, use contactId (the primary contact) or contactIds (any linked contact).

On leads, quotes and smart-process items, the five UTM fields remain available in responses but no longer pass the local filter or sort guard: Bitrix24 does not accept them in crm.item.list. Instead of a Bitrix24 422, the request now receives 400 UNKNOWN_FILTER_FIELD or 400 UNKNOWN_SORT_FIELD before Bitrix24 is called. Other operations on these fields are unchanged.

FIX-0818-5: empty workday method results are returned as null

Before

When Bitrix24 returned an empty successful result, the data field could contain a service envelope with result, total, and next fields instead of the result value.

After

POST /v1/workday/open, POST /v1/workday/close, POST /v1/workday/pause, GET /v1/workday/status, GET /v1/workday/settings, and GET /v1/workday/schedule return data: null when the successful result is empty.

Impact on integrations

Clients no longer need to extract an empty value from the Bitrix24 service response envelope.

NEW-0818-6: the field reference for orders and order statuses now returns names and explanations

Before

GET /v1/orders/fields and GET /v1/order-statuses/fields answered with nothing but a type and a read-only flag per field. There was no human-readable name and no explanation for any of the 54 fields, so a client had only the field name to go on. Generating a form or a typed model from such a schema was not possible: a name like recountFlag or empStatusId explains nothing on its own.

After

Every field of both entities now carries a label (short name) and a description (explanation) in the language of the segment. The explanation states what the type cannot: why price is accepted on create only (Bitrix24 recalculates the amount from the basket items), that requisiteLink arrives as an empty array when the link is unset, that clients, payments, basketItems and propertyValues are returned by the order card only, and that Bitrix24 requires the type field on every status update. The response grew; the set of fields and their types did not change, so existing requests keep working.

NEW-0818-7: machine issuance of promo codes: three V1 methods and two new integration-key scopes

Vibecode now exposes three V1 methods for an integration that hands out promo codes on its own: POST /v1/platform/coupons/issue issues a batch of codes inside an existing campaign, GET /v1/platform/coupons/campaigns lists the campaigns available for issuance, and GET /v1/platform/coupons/campaigns/{slug} reads one campaign by its code. Authorization is a platform integration key in the Authorization: Bearer header, with the coupons:issue and coupons:read scopes respectively; a platform administrator grants them when the key is issued.

The key issues codes but neither creates campaigns nor moves their ceiling: both stay with a platform administrator, otherwise the campaign ceiling would stop being a ceiling. A campaign is addressed by the same code (slug) that prefixes every promo code it issued, so the integrator and support share one identifier. The remainingToIssue field answers how many codes may still be issued; null means the campaign has no ceiling.

The Idempotency-Key header is required. Codes are returned once and are not stored on the platform side — only their hashes are — so there is nothing to replay: a request with an already used key gets 409 IDEMPOTENCY_KEY_ALREADY_USED with a reference to the issued batch, not a second set of codes. Issuing into a draft campaign is refused with 409 COUPON_CAMPAIGN_IN_DRAFT: codes handed out before the campaign is activated would be refused at redemption and cannot be reissued. The remaining refusals: 409 COUPON_CAMPAIGN_NOT_ISSUABLE — the campaign is finished or archived, 409 COUPON_CAMPAIGN_CAP_REACHED — the batch does not fit under the ceiling, 403 INSUFFICIENT_SCOPE — the key lacks the required scope, 404 CAMPAIGN_NOT_FOUND — no campaign carries this code.

Redeeming a promo code through a machine method is not part of this release: a code is redeemed by a person in the dashboard, under their own session and on their own account.

NEW-0818-8: promo codes for Cowork/Code tiers and the refusal codes of redemption

Vibecode now has promo codes. A partner gets a code from the organiser and redeems it in the Cowork/Code section of the dashboard: the granted tier switches on for their seat for a term the platform pays for, with no debit from the account balance. Campaigns, issuing a batch of codes and revoking unissued codes are run by the platform administrator; redemption is a user action in the dashboard and has no public API method.

A refused redemption answers with a code in the code field, and most causes collapse into a single COUPON_INVALID on purpose: "not found", "revoked", "already redeemed", "expired", "the campaign is over" and the campaign limits are indistinguishable from one another, so a refusal never confirms that a live code exists. Only the causes a person can act on stay distinguishable: COUPON_TOO_MANY_ATTEMPTS — too many attempts in a row; COUPON_PORTAL_ACCESS_GATED — the account has no Cowork/Code access yet; COUPON_SEAT_PAUSED, COUPON_SEAT_CANCELLED and COUPON_SEAT_CANCELLATION_SCHEDULED — the state of the seat prevents the grant; COUPON_TIER_DOWNGRADE_BLOCKED, COUPON_SEAT_ALREADY_ON_TIER, COUPON_SEAT_ALREADY_PAID_LONGER and COUPON_SEAT_IS_PAID — the current tier is already no lower than the granted one, or is paid further ahead. CONCURRENT_REDEMPTION stands apart: several codes of one campaign were redeemed at the same moment, and the attempt only needs repeating.

A promo code never downgrades the current tier and is never applied on top of an already paid seat — in both cases it stays with its holder and is redeemed later. A redeemed promo code cannot be revoked: revocation applies only to a code nobody has used yet.

NEW-0818-9: promo code in the Cowork/Code app: check a code and redeem it with a desktop key

The Cowork/Code app now accepts a promo code itself instead of sending the person to the dashboard. Two methods have appeared: POST /v1/cowork/coupon/preview shows what a code grants (tier, term, campaign name) without changing anything, and POST /v1/cowork/coupon/redeem redeems it and turns on the granted tier for a term the Vibecode platform pays for.

Both methods require a Cowork/Code desktop key with the vibe:cowork scope. An agent key carrying the same scope gets 403 COWORK_DESKTOP_KEY_REQUIRED: redemption is irreversible and one-shot, and there is no human behind such a key to make the decision.

The check answers 200 and reports valid: false with reason COUPON_INVALID when the code does not work. One reason covers every "code does not work" case, so the method never hints to someone guessing codes how a non-existent code differs from a revoked one. Valid here means "the code is live and the campaign is open": the seat's own conditions (already paid, already on this tier) are verified at redemption and may refuse after a successful check.

Redemption returns the granted tier, the term and an accessGranted field. false means the tier was granted but the portal administrator has not opened access to Cowork/Code yet — show that separately, otherwise the person sees success and runs into a closed door.

Affected endpoints: POST /v1/cowork/coupon/preview, POST /v1/cowork/coupon/redeem

NEW-0818-10: applications catalog in the API: list and card

The Vibecode API now exposes an applications family: GET /v1/applications returns the list and GET /v1/applications/:id a single card. Rows are scoped to the key OWNER rather than to the calling key, so applications created in the Vibecode dashboard are included too — their servers belong to other keys of the same person and never appear in GET /v1/infra/servers.

The scope parameter accepts mine, shared (applications of other people that you can access — both those shared with you personally and those open to the whole Bitrix24 account) and feed (the default), alongside the page and limit paging parameters. The card is also available to someone the application was shared with, not only to its owner; the viewer's relationship to the application arrives in the viewerState field.

The list response carries truncated next to total. In the feed scope the ordering is computed by the platform, so the selection has an upper bound: when truncated is true, total is that bound rather than the full number of applications, and there are no pages beyond it. Deriving a page count as total / limit is only valid while truncated is false; when it is true, reach for the mine and shared scopes, which have no such bound.

Every card carries two extra blocks. sources reports whether saved source versions exist and returns the latest one in the very form the version download accepts, so no upfront call for the version list is needed. activeOperation reports an operation in flight: its kind, step and start time; the value unknown means the operation did start but its outcome is not known. Both blocks are filled in only for whoever manages the application: a viewer the application was merely shared with receives an empty sources (hasVersions: false, both fields null) and activeOperation: null. The response shape does not change, so beware of the wrong conclusion: an empty sources on someone else's application means "this data is not disclosed to you", not "there are no versions".

One caveat about activeOperation: null means "no operation with a stored record", not "nothing is happening to this application". The field covers deployment, repair, server plan changes and moving a container between galaxies — other actions are not journalled by the platform and never surface here.

Where to open an application is no longer yours to work out: the card returns a ready openUrl and openTarget pair. openTarget currently has a single value — app, meaning the application's own address opens; both fields are null when there is nothing to open. The value set is closed and may grow, so treat an unfamiliar value as "nothing to open here" rather than as an error.

Important: for an application embedded into Bitrix24 both fields arrive null — the platform does not yet know the address such an application opens at inside the account. Its own address is deliberately NOT substituted into openUrl: that address leads to the gateway sign-in page rather than into the application, so following it would look successful without being so.

The isEmbedded field tells those two states apart — "embedded, opens inside Bitrix24" versus "not published yet". Both arrive with an empty open pair, yet the text a user should see differs. Do NOT infer embedding from the presence of a server: an embedded application with no server of its own is a normal state (the embedding is done, the code has not been deployed yet), and the flag does not depend on the server at all. The field is disclosed both to the owner and to someone the application was shared with.

The server summary gained a reachable flag — true when the server both runs and answers over the network. It is separate from status because those are different facts: a server can be up while the network tunnel to it is not, and by status alone such an application looks healthy. A client cannot check this from outside, so the platform computes the flag.

The flag already implies the RUNNING state: it never arrives true for another server state, so there is no need to conjoin it with status. For an application inside a galaxy (server.kind: "GALAXY_APP") the second half of the flag is taken from the galaxy HOST, not from the container itself — the host holds the connectivity, the container has no tunnel of its own by design. Hence a consequence worth knowing up front: a freshly created container that has not reached RUNNING yet (it only does so after its first source upload) arrives with reachable: false even on a fully healthy host. That means "the container is not up yet", not "the host is unreachable" — the flag alone cannot tell the two apart, status can.

The server summary gained a lastDeployedAt field — when the application was last deployed successfully. It is the only signal in this section that an application is actually lived in: updatedAt only moves when the card is edited, and sources.latestSavedAt means "code saved" and reaches only whoever manages the application. The stamp is written by the deployment itself at the moment it records success, so a failed deployment never moves it. Important: the field carries no history: for servers created before it existed it arrives null until their next deployment — we did not reconstruct the history, because the available source covers only one of the three deployment paths and a date would appear for some server kinds while missing for others.

Two more things worth knowing up front. The application id from this section and the id from GET /v1/apps are different values of different entities: an application card here, an application registration on the Bitrix24 account there. And the same thing by meaning arrives under different names: name here, title there. Do not carry one over into the other — the fields are not synchronized.

The list ordering is now stated explicitly so a page walk is reproducible. In the feed scope: pinned by you → your own → other people's, and within a group by updatedAt newest first, ties broken by id. In mine and shared: by createdAt newest first, ties broken by id. That secondary key is not a formality — applications created in a batch carry identical timestamps, and without it two pages of one walk could overlap or skip an application. Important: updatedAt only moves when the card itself is edited — a deployment does not touch it, so "freshness" in the feed means "when the card was last changed", not "when the application was last deployed".

2026-08-17

FIX-0817-1: repeated PostgreSQL runtime deploy no longer fails on an existing database

Before

POST /v1/infra/servers/:id/deploy with a PostgreSQL runtime tried to create the app database again on a repeated run, so the runtime setup step could fail.

After

The node20-pg, node20-pg-redis, node20-rag, python311-pg, and python311-rag runtimes create the app database only when it is absent. A genuine creation failure still stops the deploy.

Impact on integrators

A repeated deploy with the same PostgreSQL runtime no longer requires deleting the database manually or changing the runtime.

FIX-0817-2: calls statistics reference shows working filters and sorting

Before

The machine-readable hint for GET /v1/calls/statistics suggested non-existent date-range fields and did not explain that the sort field and direction are separate parameters.

After

The hint and OpenAPI show filter[>CALL_START_DATE] / filter[<CALL_START_DATE] comparisons, the sort + order pair, and the actual single-page limit of up to 50 records. The adjacent call-management operations now also use the mounted :callId paths and the actual registration, finish, transcription, auto-call, and callback request bodies.

Impact on integrators

Use canonical Bitrix24 comparison operators in filter keys and pass the sort direction in the separate order parameter.

FIX-0817-3: the Cowork/Code deploy-key mint now recovers a fleet stranded by earlier mints

Before

POST /v1/cowork/deploy-key moved links onto the fresh key only from the key that was active at mint time. Anything left on keys revoked earlier was never picked up: those servers stayed out of GET /v1/infra/servers, answered 404 on a single read and 403 WRONG_KEY on publish. When the owner had no live deploy key at all, the mint moved nothing, so requesting another key did not repair such a loss either. The only remaining path was manual: rebinding the server to a live key in the dashboard.

After

A mint now drains links from every previously revoked project key of the same owner and portal, not just the currently live one — up to five keys per call, newest first. Server ownership, the application card, live access tokens and the read scope of deploy operations move onto the fresh key inside the same transaction as the mint itself, so the server list and publishing work immediately after the response. The "no live key" case is no longer special: links are moved on a first mint too.

Influence on integrators

No client change is required. The previous entry's caveat — that a stranded fleet comes back only through a manual rebind in the dashboard — no longer applies; requesting the key again is enough. If links piled up on more than five keys, later mints drain the rest; the key lives for seven days, so this needs no separate action.

NEW-0817-4: quota relief is visible in the Cowork/Code subscription responses

GET /v1/cowork/me and GET /v1/cowork/state now return a relief block — the moments Vibecode platform support last reset the usage counters and last granted a temporary limit increase. Both stamps come to the hour and stay visible for 7 days, after which the field is empty. Along with the block, the subscription summary now returns boostPct and boostExpiresAt — the size and the deadline of an active increase, which were carried by the full state only before.

An empty relief.boostGrantedAt does not mean there is no increase: the stamp is there for a one-off notification and lives for 7 days, while an increase is granted for up to 30 days. Whether an increase applies is told by boostPct, and by nothing else.

The capability is switched on account by account. Until it is on, none of the keys listed above are present in the response body at all, so test for the presence of the key rather than for its value. Existing calls keep working unchanged.

NEW-0817-5: notification type dictionary

GET /v1/notifications/schema is now available — a directory of the Bitrix24 account modules and the notification types they send. The operation takes no parameters.

The response carries a modules array; every module has an identifier, a name and a list of types. The module identifier matches the notifyModule field of a notification in the feed and the type identifier matches notifyEvent, so the directory answers the "show a human a readable name instead of a technical code" task and fits notification-settings screens.

Bitrix24 hands the directory over as a map whose key repeats the module identifier inside the entry, and the Vibecode API unwraps it into an array. The element order comes from the account and is not a sort contract. The contents depend on the account and change as Bitrix24 is updated, so cache the response but re-read it when you meet an unfamiliar module or type.

NEW-0817-6: Bitrix24 account calendar settings are available through the API

A new endpoint GET /v1/calendar/settings returns the Bitrix24 calendar settings: work day start and end, weekly days off, holidays, working Saturdays and the first day of the week. These are the values the Bitrix24 interface uses to mark non-working days. The request takes no parameters and needs a key with the calendar scope.

The fixed response fields arrive in camelCase — workTimeStart, weekHolidays, yearHolidays. Section addresses for non-standard calendar types arrive as one field per type, named exactly as the account returns it, so the response field set is not fixed.

When the key owner is not an employee of the account, Bitrix24 returns a reduced set of two fields carrying default values instead of the account settings. Such a response is indistinguishable by value from a configured account, so it carries meta.warnings with the code calendar_settings_partial.

The endpoint has a limit of its own — 120 requests per minute per Bitrix24 account, on top of the shared request limit to Bitrix24. The settings change rarely, so the response is meant to be cached on the client side rather than polled.

Calendar events and sections remain available as entities — /v1/calendar-events and /v1/calendar-sections.

2026-08-16

NEW-0816-1: the app icon accepts raster files, and a Bitrix24 portal can push one itself

The icon upload POST /v1/infra/servers/:id/icon now accepts raster formats — PNG, JPG, GIF, WEBP, up to 5 MB and up to 4 megapixels (2000×2000, for example) — in addition to SVG. The format is detected from the file contents, not from its name or its Content-Type header. Whatever you upload, the serve URL still returns a 256×256 PNG: the platform scales the image into a square, keeping its proportions and padding the rest with transparency. Existing SVG uploads keep working unchanged: the SVG limits — 256 KB and the same 4096×4096 ceiling as before — are untouched.

New refusal codes: ICON_UNSUPPORTED_FORMAT for a format that is unrecognized or unsupported, ICON_TOO_LARGE for a file above the size limit, ICON_TOO_MANY_PIXELS for an image with more pixels than the platform will unpack, ICON_RASTERIZE_FAILED for a file that cannot be read.

In your Vibecode account the icon picker narrowed the other way: the server card and the application card take PNG, JPG, GIF and WEBP, and now refuse SVG — that format stays in the API alone.

The other half of the change is on the portal side: an app owner can now replace the icon straight from the Bitrix24 catalog card, and the portal pushes it to the Vibecode platform together with the title and the description. That icon lands on the same catalog card as one uploaded through the API.

NEW-0816-2: two fields describing a temporary limit increase in the Cowork/Code state

The GET /v1/cowork/state response now carries two fields describing a temporary limit increase: boostPct — the increase in percent (100 means limits are doubled), and boostExpiresAt — when it ends. With no increase active they read 0 and null.

The pctUsed shares of all three windows already account for the increase, so there is nothing to apply on the client side — the fields exist so you can show the size and the deadline to the user.

NEW-0816-3: new 402 company_budget_exhausted rejection on calls that spend credits

Before

The only money-related rejection on /v1/search/* and on AI calls was insufficient funds on the account — INSUFFICIENT_BALANCE. An administrator had no way to cap the spend of an individual employee or of the whole account.

After

An account administrator can set a monthly budget for metered spend — for the whole account and for an individual employee. Once the budget is exhausted, web search and research calls, as well as AI calls — POST /v1/chat/completions, POST /v1/embeddings and POST /v1/audio/transcriptions — that spend credits receive a 402 with the code company_budget_exhausted.

The rejection body carries two extra fields. scope tells whose budget is exhausted: USER is the caller's own budget, PORTAL is the budget of the whole account. canRequest tells whether an increase can be requested from the product: true for a personal budget, false for the account budget, which only an administrator raises.

The rejection is returned only on calls that actually spend credits: a search made with the customer's own key costs nothing and keeps working when the budget is exhausted, and so do AI calls made with the customer's own key, calls served inside the plan quota, and calls covered by a subscription. A call already in flight is completed: the limit applies from the next request.

Budgets are enabled separately and are off by default, so accounts without them see no change.

FIX-0816-4: the Cowork deploy-key handout no longer loses servers

Before

POST /v1/cowork/deploy-key revoked the previous key but left everything that referenced it behind: server ownership, the application card and live access tokens. Versioned infrastructure reads are scoped to the calling key, so after every re-issue the earlier servers dropped out of GET /v1/infra/servers, answered 404 on a direct read and 403 WRONG_KEY on deploy. The only way back was the dashboard.

After

The handout moves those links onto the fresh key, exactly as key rotation does. The server list and deploy work under the new key straight away, containers on a shared galaxy host included.

The read scope of started operations moves with them, so GET /v1/infra/operations/{operationId} keeps returning the outcome of a run begun under the previous key. A client whose transport dropped — and which therefore asked for a new key — used to get 404 on its own operation, indistinguishable from "no such operation".

Impact on integrators

Nothing to change: from this fix onward a re-issue no longer loses the links.

Important: the fix works forward and does not recover what is already lost. The move starts from the key that is active at handout time, while orphaned links sit on keys revoked earlier, so they are outside its reach. If your servers disappeared before this rollout, restore them by hand: in the Vibecode dashboard, open the server card and bind it to the key you use now.

The key lives for seven days and is not re-issued on a schedule. If it goes untouched for longer, the servers stay with the expired key and become visible again after the next handout, which moves the links off it.

2026-08-15

BC-0815-1: combo runtimes with a database no longer slip into Galaxy silently

Old format supported until: not provided

Before

Deploying an app into Galaxy with a runtime that promises a database (node20-pg, node20-mysql, node20-redis, node20-mysql-redis, node20-pg-redis, node20-rag, python311-pg, python311-mysql, python311-redis, python311-rag, php83-mysql) succeeded. The database suffix was stripped and the app got the language image only: no database engine, no connection variables (DATABASE_URL, PG*). The failure showed up on the first database call.

After

Such a deploy is refused up front: 400 with code GALAXY_RUNTIME_DB_UNSUPPORTED, a details.suggestedRuntime field (the language replacement — node20 instead of node20-pg, for example) and a recovery hint. The catalog GET /v1/infra/runtimes now returns supportedPlacements on every runtime: ["standalone"] — dedicated virtual machine only, ["standalone","galaxy"] — Galaxy as well. The name and packages fields are unchanged: they describe the dedicated-machine install, where a combo runtime really does install the database.

What integrators should do

Filter the catalog by supportedPlacements containing galaxy before a Galaxy deploy. If a Galaxy app needs a database, take a language runtime and pass the connection string of an external database through env. If the database must live on the same machine, create a dedicated virtual machine (placement: "dedicated", create without source) and deploy the original runtime to it in a second step. Apps already running are unaffected: the refusal only happens on a new deploy.

NEW-0815-2: the bound placements list now states whether the account was checked

The GET /v1/placements response gained three optional fields. The portalSync field states how the reconciliation of the list against the Bitrix24 account ended: ok — the account returned every bound code, drift — the account did not return some of the codes, unknown — no reconciliation happened. The reason for a value other than ok is returned in portalSyncReason — no_oauth_session, empty_vibe_list, b24_unreachable, unpublished or missing_on_portal. On a divergence the codes that are listed as bound in Vibecode and were not returned by the account are named in missingOnPortal, and the same codes get a line in warnings.

An application withdrawn from the catalog is not treated as a divergence: the unpublished value states that the platform itself removed the placements from the account and kept the codes for republishing. The reconciliation runs when a session token is passed together with the application key and the application has bound placements. Without those conditions portalSync is returned as unknown — the response behaviour did not change, it is simply stated explicitly now.

Previously the outcome had to be inferred from the presence and the length of the handlers array, which did not separate "the account answered and the code is not in the answer" from "the account response could not be obtained": both produced an empty array. The handlers field is now absent in the second case, and the reason is visible in portalSyncReason. Existing calls keep working, the new fields are additive.

FIX-0815-3: AI quota is resolved by plan in every Western zone

Before

A Bitrix24 account plan is recorded as "account zone plus edition" — for example jp_pro100. The platform stripped the zone prefix for only ten of the Western zones, so an account in the cn, id, it, vn, jp, ms, th, hi, co or ae zone matched no plan setting at all. Its monthly AI quota was then sized by the fallback rule instead of by its own plan.

After

The prefix is stripped in all twenty-one Western zones, and the quota is sized by the setting of the plan the account actually holds. No client-side change is required; for affected accounts the monthly quota size changes from the next billing period — up or down, depending on how their plan is configured.

NEW-0815-4: an app can be added to the Bitrix24 catalog with a dedicated call

A new call is available — POST /v1/infra/servers/:id/b24-catalog/publish. It creates the app card in the Vibecode apps catalog on the Bitrix24 account. Previously the card appeared only after a successful deployment, so an app brought up any other way was missing from the catalog, and granting access to people did not surface it.

GET /v1/infra/servers and GET /v1/infra/servers/:id now return a b24CatalogSync block with status, itemId, attempts, pendingOp and eligible. A non-null itemId is the "the app is in the catalog" signal. The eligible field answers a different question — whether a card can exist at all: an agent runtime, a galaxy host, a server without a subdomain and a server with no app deployed to it never get one.

Existing calls keep working unchanged: editing the access policy or the access list still does not create a card, it updates an existing one.

FIX-0815-5: the Cowork monthly limit now follows the tier grid without waiting for a renewal

Before

/v1/cowork/state and /v1/cowork/me measured a paid seat's monthly window against the volume frozen when the seat was bought. When a platform administrator raised a tier's monthly limit, the new value reached the seat only at its next renewal: month.pctUsed did not move, and a seat sitting at exhausted stayed blocked until the paid period ended even though the tier limit had already grown. The weekly and five-hour windows updated immediately, so the three windows of one seat answered by different rules.

After

A paid seat's monthly window is measured against the greater of two values: the live tier limit and the volume sold for the current period. A raise applies at once — month.pctUsed drops with no request made, and month.exhausted returns to false when the new limit exceeds what was spent. A cut does not touch the paid period: until it ends the seat is measured against the volume sold, and the new value takes effect from the next period. A free seat is still measured strictly against the live limit.

The response still carries no absolute numbers — only the shares, the exhausted flag and the resetAt moment change. A client caching month.pctUsed should re-read the state before deciding to block, rather than assuming the share only ever grows.

2026-08-14

NEW-0814-1: thirty-one more live operations are now in the machine schema

Thirty-one V1 operations that were already live and documented are now included in GET /v1/openapi.json: smart-process custom fields, requisite links, CRM card configuration, configurable activities, mail, task time tracking, server icon and unstick operations, bot transfer and human-resources node search, plus app blueprints. The methods and their responses did not change — only the machine-readable descriptions were added for clients and agents that build integrations from the schema.

BC-0814-2: port pinning refuses instead of confirming falsely

Old format supported until: not provided

Before

On a pinned server PATCH /v1/infra/servers/:id/port wrote the requested port into the agent settings without checking whether any process on the machine was listening on it. The public address could stop answering entirely after such a change, and the only way back was the non-obvious port: 0. A verified: true reply meant no more than that the agent had come back online: an agent that came up with automatic port detection, that is without the pin in force, produced exactly the same confirmation. Two calls in a row could leave the agent on the port of the other request, and both answered with success.

After

A port nothing listens on is refused with 409 PORT_NOT_APPLIED before the settings are rewritten; the message lists the ports the agent sees listening. Entry NEW-0812-3 stated that a pinned server never receives this code — it does, in exactly this case and without the agentError field.

The confirmation is stricter: verified: true now means that the agent settings carry the requested port, that the agent really did restart, and that it came up with the pin in force rather than with automatic detection. The reply additionally carries data.pinned — whether the machine is still pinned after the call.

While a port change is still in progress, a second call for the same server receives 409 SERVER_BUSY. The endpoint itself now has a rate limit of 10 requests per minute.

What integrators should do

Start the process on the target port BEFORE changing the port: the order "pin the port first, launch the application on it afterwards" now answers with a refusal rather than a success. Do not send a port change in parallel with a deployment or with another port change of the same server — wait for the previous call to answer. Stay within 10 requests per minute.

FIX-0814-3: the dimensions parameter for the bitrix/embeddings model

Before

The dimensions parameter was declared in the POST /v1/embeddings schema, but any request carrying it for the bitrix/embeddings model received 400 ai_provider_rejected — whatever the value, including the dimensionality the model already returns.

After

For bitrix/embeddings the parameter works: an integer from 32 to 4096 is accepted, and the response carries a vector of that dimensionality re-normalised to unit length. A value outside the range is rejected with 400 invalid_request and a param field. Requests without the parameter are unchanged: the full dimensionality is 4096.

A smaller dimensionality neither reduces input-token usage nor speeds up processing — the saving is on the integrator's side, in index size and search speed. Vectors of different dimensionality must not be mixed in one similarity index. Details — Create embeddings.

FIX-0814-4: leading service markers are no longer included in model content

Before

After a tool call, the final answer from POST /v1/chat/completions sometimes started with service markers before the text. A response_format request whose answer was only those markers returned 200 and a non-empty content.

After

Leading service markers are removed from content. If no text remains, content is null — the same as a textless answer. For a response_format request this is the already documented empty-content case without tool_calls: HTTP 422 and code structured_output_truncated. If text remains after the markers are removed, the response stays 200 with the cleaned content.

Impact on integrators

In the common case no client change is required: the answer is the same minus the prefix, and stripping the prefix on your side stays safe. The change does affect you if you relied on a 200 for a response_format request whose answer carried no text: that response now comes back with 422 and structured_output_truncated, as described on the method page. The markers are removed in streaming mode as well. The usage field is not recalculated.

FIX-0814-5: the blocking server wake returns WAKE_TIMEOUT far less often on a cold start

Before

The blocking wake — POST /v1/infra/servers/:id/wake with ?wait=true, and the automatic wake of a sleeping server on POST /v1/infra/servers/:id/deploy — returned 503 WAKE_TIMEOUT in two cases that had nothing to do with how long it waited. When the cloud lost the start command, the platform never re-issued it and eventually reported that the machine had not come up. And when the agent connected its tunnel before the platform refreshed the server status, readiness was still not recognised, so a machine that was already up was put back to sleep.

After

While waiting for readiness, the platform now re-checks the machine state with the cloud and re-issues the start command if it never landed. A connected tunnel counts as proof of readiness on its own: the server moves to running and the response returns without waiting for the next status refresh. Error codes, the response shape and the wait window (~6.5 minutes, then 503 WAKE_TIMEOUT and the server returns to sleeping) are unchanged, so clients need to change nothing. A machine that genuinely did not come up still reports WAKE_TIMEOUT honestly.

FIX-0814-6: a fractional or malformed path id no longer returns a DIFFERENT record

Before

GET /v1/tasks/1.5 answered 200 and returned the record with id 1: the non-integer value was forwarded to Bitrix24 as-is, Bitrix24 truncated it, and the client got a DIFFERENT real record instead of an error. Update and delete behaved the same way — a write silently landed on the wrong record. This affected entities with an integer id; the wrong-record substitution was observed live on twelve of them (tasks, workgroups, users, departments, statuses, storages, sites, pages, folders, timelines, Open Channels configs, requisite presets), while for the rest Bitrix24 rejected the request itself. Some entities (deals, for example) already answered 400, so the behaviour differed inside one API.

After

A non-integer id is rejected with 400 INVALID_PARAMS before the Bitrix24 call — consistently on read, update and delete, in single requests and in batches (/v1/batch, /v1/<entity>/batch). The rule applies to every entity with a numeric id. Integer values work as before. Entities whose id is not a number (order statuses N/P/F, currencies, business-process codes) and chats, which accept the chat1 form, keep their previous behaviour.

NEW-0814-7: reading the notification feed and the unread counter

GET /v1/notifications is now available — it reads a user's notification feed together with the unread counter. Until now the Vibecode API could only send notifications, mark them read and delete them, so an inbox application had to keep a second, separate Bitrix24 integration just to read them.

The response carries the notification list, the cards of their authors, the total counter, the unread counter and a hasMore flag. Page size comes from limit (1 to 50, 50 by default); a value outside the range is brought to the nearest bound, and the size actually used is always visible in meta.appliedLimit. Paging walks the Bitrix24 cursor: lastId and lastType are sent together. To read the unread counter without pulling a page, call with limit=1.

The feed belongs to the token owner — the operation has no parameter selecting whose inbox to read, so a personal key returns its own owner's feed, while a given employee's feed requires an OAuth application key with an Authorization: Bearer header. The feed is not filtered by application: it also carries other applications' notifications and the Bitrix24 account's own system ones, so pick yours by notifyTag or notifyModule.

NEW-0814-8: Workday history in the V1 API

A new endpoint is available — GET /v1/workday/records returns one employee's workday history over a period. It reports the start and end of the day, seconds worked, break length and the approval flag, so lateness and overtime reports can be built through the Vibecode API without a separate integration with the account's time tracking.

userId is mandatory: the Bitrix24 account refuses the call without it. The period is set by the optional from and to in ISO-8601 with an explicit timezone offset or Z; with no period given, the last 7 days are returned. A bare date is rejected — a workday boundary depends on the timezone, and silently widening it to UTC would reclassify the very lateness the endpoint exists to report.

A single request returns at most 50 records; page deeper with offset or page. meta.hasMore signals a continuation. The meta.total field is present only when the page came back shorter than the requested limit: the size of the selection is known exactly in that case, whereas on a full page it is not, and no invented number is put there.

The scope is unchanged — timeman. Rights to read another employee's records are decided by the Bitrix24 account: they belong to an administrator or the employee's direct manager.

FIX-0814-9: the INT_VIBE_PLUS_REQUIRED refusal now points at the plan page inside the account

Before

For the INT_VIBE_PLUS_REQUIRED code, details.upgradeUrl and alternatives[0].url carried the generic Bitrix24 pricing page. A Vibe+ plan is enabled inside the account itself, so that page did not show what to actually do.

After

Both fields now carry an address on the customer account that opens the explanation for the required plan: https://<account domain>/online/?feature_promoter=limit_why_pay_tariff_vibe. The servers.create slot of GET /v1/me returns the same address — it used to disagree with the refusal body.

When the account domain cannot be recognised, both fields still carry the generic pricing page: no broken address is ever returned.

Impact on integrators

Nothing to change. The response shape is unchanged and both fields remain address strings. A client that sent the user to details.upgradeUrl now lands them on the plan they need instead of a generic price list. The refusal code, the field set and the response status are unchanged.

BC-0814-10: audio transcription accepts the file only in the file field, never truncates it silently, and returns a recognition refusal as 400

Old format supported until: not provided

Before

POST /v1/audio/transcriptions took the first multipart file part regardless of its field name and did not check the filename extension: an unknown extension was labelled audio/mpeg and forwarded for recognition. A file over the 25 MB limit was not rejected but silently cut at the limit: the answer was 200 with a transcript of only the beginning of the recording, and it was billed — nothing in the response indicated the cut. Any non-2xx from the recognition service came back as 502 ai_provider_unavailable, including a rejection of the request body.

After

The file part must be named file, otherwise 400 no_file — whatever the size of the file sent. That check runs before the recognition call. The filename extension is NOT checked: the recognition service detects the container from the content, so rare voice-recorder formats, a name without an extension and a part with no name are accepted exactly as before. A file the recognition service could not read comes back as 400 ai_provider_rejected. A file over 25 MB is rejected outright — 413 request_too_large, nothing charged; a truncated transcript no longer happens. A recognition refusal with HTTP 400 or 422 is returned as 400 ai_provider_rejected with a providerStatusCode field; rate limiting on its side is returned as 429 rate_limit_exceeded with a Retry-After header; unavailability and authentication errors stay 502 ai_provider_unavailable.

Integrator action

Name the file part file — a previous name such as audio no longer works. Split recordings above 25 MB before sending: such a request is now rejected rather than partly transcribed. If your code branched on the status, note that a body rejection now arrives as 400 rather than 502, and retrying such a request cannot help. There is no need to change extensions: the list includes the formats that used to be accepted silently. The old behaviour is not coming back.

NEW-0814-11: catalog product image metadata

Added GET /v1/catalog-products/:productId/images for a product-scoped snapshot of native images and GET /v1/catalog-products/:productId/images/:imageId to retrieve one image. The snapshot includes the detail picture, preview picture, and MORE_PHOTO gallery, but not files stored in other custom properties. Both methods require the catalog scope, return an untrusted detailUrl, and never expose the signed downloadUrl; server-side fetching requires the platform SSRF policy. Documentation.

NEW-0814-12: audio transcription can now draw on the Cowork/Code subscription quota

Calling POST /v1/audio/transcriptions with a key carrying the vibe:cowork scope used to consume nothing: transcription was metered against the Bitrix24 account AI quota, which subscription keys skip. A platform administrator can now price the transcription model per minute of audio, and such a call draws on the subscription quota, exactly like chat does.

Until a price is set the behaviour is unchanged: the call is free and no subscription limit applies to it.

Once a price is set and the quota window is exhausted, the endpoint answers 402 with code cowork_quota_exhausted — the same code chat already returns — plus a Retry-After header holding the seconds until the window resets. The body carries window (5h / week / month), resetAt and nextTier.

Response formats that carry no duration (text, srt, vtt) are billed at the per-call price, because the audio length is not reported for them.

FIX-0814-13: a wake schedule no longer shortens the auto-sleep you set

Before

When a server carried both an auto-sleep timeout (sleepAfterMinutes — 30, 60 or 240 minutes) and an enabled wake-schedule window, the idle threshold was silently replaced with the platform's short 15-minute one. The server fell asleep after 15 minutes instead of the value it was given, while GET /v1/infra/servers/:id and the server card kept reporting the chosen value — the divergence was not visible anywhere.

After

The value you set applies as set: a schedule only decides when the server wakes up. The short threshold stays exactly where it was introduced for — a server with no auto-sleep at all (sleepAfterMinutes: null), so that it still sleeps between windows. No integration change is needed; servers holding both an auto-sleep timeout and a schedule now stay up until their own threshold.

NEW-0814-14: a write with a lossy-charset value now reports it

Before

When a title or description arrived with its non-ASCII characters already replaced by question marks, the platform stored the value silently. The catalog card then showed ????????? ????????, and the only way to notice was to look at it.

After

The value is still stored, and the response now also carries a warnings array naming the fields that arrived with no non-ASCII character left, suggesting the text be re-sent as UTF-8. This applies to POST /v1/infra/servers and PATCH /v1/infra/servers/{id} (displayName, description), POST /v1/infra/servers/{id}/deploy (displayName, description), POST /v1/apps and PATCH /v1/apps/{id} (title), POST /v1/apps/{id}/publish (catalogTitle, catalogDescription). The warning is emitted only for a field the call actually applied: re-sending the same value, or a field the deploy dropped because it was already set, stays silent. The field is optional and absent when there is nothing to report, so existing clients keep working unchanged.

2026-08-13

FIX-0813-1: a failed native-module build now states its own cause instead of "Python not found"

Before

A Node app with a dependency shipping compiled code (better-sqlite3, for one) deployed only sometimes. Such dependencies install in two steps: first a prebuilt file is downloaded, and if that fails the module is compiled from source on the spot. When the download broke on the external network, the second step began and failed — the app image carries no build tools. The deploy response and the app card then showed the last line of that second step, Could not find any Python installation to use, which pointed away from the real cause: the customer went looking for a bug in their own code and in their Python version, while neither was broken. The failure category came out generic — INSTALL_FAILED, with a hint about a missing compiler.

After

This failure has its own category, NATIVE_PREBUILD_UNAVAILABLE, delivered in the category field of the 502 GALAXY_APP_BUILD_FAILED response and in the app card's buildHint. The hint says what is true: the prebuilt artefact could not be downloaded, the external source did not respond, this is temporary, retry the deploy in a few minutes. The category is assigned only when both pieces of evidence appear in the build log — the download broke on the network AND there was nothing to build from source with; failures a retry cannot cure (no prebuilt artefacts are published for this platform, the host ran out of disk) stay out of it and keep their previous text. The client retries the deploy — the platform does not re-send the build on its own.

FIX-0813-2: API response shapes are described in the machine-readable schema

Before

The machine-readable schema did not show the actual response shapes for POST /v1/duplicates/find and GET /v1/lists/{iblockId}/elements. This made it harder to handle duplicate-search results and Bitrix24-native list-element fields.

After

The schema describes an entity-type keyed object or an empty array for duplicate search, and a list-element array in its envelope with dynamic property keys and a meta.total counter, without changing the actual API response.

Impact for integrators

Integrations can use the machine-readable schema to select the response shape. For list-element requests, account for the limit parameter being ignored.

NEW-0813-3: the real state of a sleeping galaxy app in the server GET and in the logs answer

GET /v1/infra/servers/:id now returns a reachability block for a galaxy app, answering the question "can the app respond right now". The status field is unchanged — it is the state of the app record, and during a wake it lags behind the machine: the record stays sleeping while the platform brings the galaxy up, which takes minutes on a cold machine. Beside it, reachability carries the summary effectiveStatus, the carrying galaxy state hostStatus and hostTunnel, the live-read container and forwarder, the check outcome probe and its time probedAt. The check runs only against a galaxy that is up and never wakes a sleeping one, so for a sleeping galaxy container and forwarder arrive as unknown. For every other server type the block is null.

The GET /v1/infra/servers/:id/logs answer for an app on a sleeping galaxy gained a recovery field and names the path that works: the wake call, the logsPreserved marker (the wake starts the same container, so lines written before the sleep stay in the log), the cold-galaxy boot budget in seconds, what to check readiness with, and whether a recurring wake window is available for this app. The hint field is still a string and now names the wake call as well.

The states and the order of actions — Galaxy app sleep and wake.

FIX-0813-4: file download declares its required scope in openapi.json

Before

The GET /v1/files/{fileId}/download operation carried no x-required-scope field in the machine-readable spec, although the runtime answers 403 SCOPE_DENIED without a scope. A client or agent deriving key scopes from the spec read it as "no scope needed" and was refused on the first call. The same operation also appeared in every openapi.json?scope= slice, including slices of other modules.

After

The operation declares x-required-scope: disk, its primary scope. The handler also accepts crm: a key holding only that scope downloads a file attached to a CRM file-type user field. The second scope is declared in a new optional x-alternative-scopes field next to the primary one. In slices the operation is kept for openapi.json?scope=disk and ?scope=crm, and is gone from the rest.

Integrator impact

A client reading only x-required-scope will request disk and keep working as before. A client holding a crm-only key can now see from the spec and from the operation page that the call is available to it — previously that was stated only by the refusal message and the key self-description in /v1/me.

FIX-0813-5: A readable build error instead of raw builder output and external addresses

Before

When a build failed because the base-image registry was unreachable, provisionError and the 502 body carried the builder output verbatim: the external registry name, the request path and a public IP address. Other build failures could also carry external links and public IP addresses in their text.

After

An unreachable image registry is now described by a fixed sentence: the cause plus the action — re-send the same deploy in a few minutes, the slot and its data are untouched. The failure category (provisionErrorCategory) and the retryable flag are unchanged. For every other build failure the cause is still passed through as-is, but external addresses in it are replaced with markers — full links, a scheme-less image-registry name where the line itself is about the image, an address named with no path at all in a network-failure line (getaddrinfo ENOTFOUND …, "could not resolve host"), and public IP addresses. First-party platform addresses, local and internal ones stay visible, and so do the image name with its tag, file names and package names: the marker goes where the text itself calls the token an address — so a package named socket.io stays readable even though its shape is identical to a registry's. One exception: a four-part numeric run (11.0.16.1) is indistinguishable from an IP address, so a version of that shape becomes a marker too.

Impact on integrators

Nothing to change: error codes, categories and the retryable flag are the same. A client that parsed provisionError by substring now gets a stable sentence for this failure class instead of changing builder output, and the full build log is still available in the buildLog field of the same response.

NEW-0813-6: the agent bundle manifest now reports the runtime verification mode

Two optional fields were added to the GET /v1/agent-bundles/:kind/manifest.json response.

runtime_integrity is either "on" or "off" and tells the agent whether to verify the files of its environment against the checksums recorded at install time. The agent verifies only on "on"; an absent field means verification is disabled.

runtime_integrity_budget is an integer that the platform currently always sends as one. The agent reads it as permission: above zero means recovery is allowed, zero forbids it. The agent caps the attempt rate on its own at one per hour, so values above one do not change behaviour. Recovery is governed by a platform setting rather than by this field; the field exists so that an agent receiving no value performs no recovery at all.

Existing requests are unaffected: the fields are optional, and the remaining manifest fields and the archive checksum are unchanged. Clients reading the manifest need to do nothing.

NEW-0813-7: the agent bundle manifest gained a targeted runtime repair operation

The operations object of GET /v1/agent-bundles/:kind/manifest.json now carries a repair_runtime key.

The operation reinstalls the agent runtime in place when the files of its environment have diverged from the hashes recorded at install time. Previously such a divergence could only be cleared by recreating the whole application.

Its available_to field holds the single value admin: the operation is rare and manually triggered, so a call made on behalf of scheduled jobs is rejected with OPERATION_FORBIDDEN. Success requires more than a zero exit code — the agent must also confirm that the environment now agrees; otherwise the operation answers status: "failed" with the reason in the error field.

Existing requests are unaffected: the other operations, the manifest fields and the archive checksum are unchanged. Clients reading the manifest need to do nothing.

FIX-0813-8: The reauth refusal no longer advises OAuth to keys that have none

Before

POST /v1/bots/{botId}/reauth answered 410 REAUTH_REQUIRED with one and the same advice on any dead credential — re-run authorization through POST /v1/oauth/authorize, or recreate the personal key. A key that reaches Bitrix24 through an inbound webhook has no way to follow it: there is no authorization flow and no refresh token behind such a key. Its owner read the instruction and hit a dead end.

After

The refusal text now depends on how the key authorizes, and error.details carries a new credentialKind field — oauth, webhook or unknown. For a webhook-backed key the refusal names the real cause (the webhook is dead, most often deleted on the Bitrix24 side) and the real remedy — re-minting the webhook, which preserves the key id and string so linked bots keep working. For an OAuth-backed key the text is unchanged.

Impact on integrators

Nothing to change: the response code and its status are the same. A client that parsed the refusal text as a string will see new wording for webhook-backed keys — branching on error.details.credentialKind is the sturdier option.

FIX-0813-9: deleting a galaxy app on a host that cannot be woken now answers a terminal 409

Before

DELETE /v1/infra/servers/{id} for an app on a galaxy host that cannot be woken (frozen balance or a wake block) answered 502 GALAXY_HOST_UNREACHABLE with an error.hint object and advice to retry later. That advice never worked: the wake was refused, not failed, so clients kept retrying until their own timeout.

After

The refusal is terminal and arrives as 409 GALAXY_HOST_WAKE_BLOCKED. The body carries error.reason with the cause: BILLING_FROZEN, ACCESS_EXPIRED, STOPPED or UNKNOWN. The error.hint object is gone on this path — it described recovering an unreachable host, and there is nothing to recover here; for genuine unreachability the 502 with hint stays unchanged. Retrying is pointless — the cause has to be cleared.

The 409 GALAXY_HAS_APPS text for deleting the host itself was corrected too: deleting a galaxy together with its apps is available in the dashboard, and the public API has no such operation.

NEW-0813-10: the Marketplace trial can be started from a Cowork/Code desktop key

A new endpoint POST /v1/cowork/activate-market-trial starts the one-time Marketplace trial for the Bitrix24 account the calling Cowork/Code desktop key is bound to. Until now the programmatic path existed only for personal keys and application keys — the desktop key was rejected by POST /v1/portals/{id}/activate-market-trial, and that refusal stays in place.

There is no path parameter: the account comes from the key, so a client never needs an internal identifier. The body is required — {"acknowledgedOneTimeConsumption": true}, the literal true and nothing else. With it the client confirms that the user was shown that a one-time, non-revocable trial is being started, and was told when it ends. The confirmation is recorded in the account's audit trail.

A successful answer is {"success": true, "data": {"status": "activated", "trialEndsAt": "…"}}; instead of activated you may receive already_active (the trial or the paid access is already in force) or pending — the activation went through and Bitrix24 has not confirmed it yet, and in that case the request must not be repeated. The length is set by Bitrix24, so show the user the date from trialEndsAt rather than a number of days of your own.

Refusals: 400 DISCLOSURE_REQUIRED (no confirmation), 403 INSUFFICIENT_SCOPE (the key has no vibe:cowork right), 403 COWORK_DESKTOP_KEY_REQUIRED (a key of another class — an agent seat key carrying the same right, for example), 403 WRITE_BLOCKED_READONLY_KEY, 409 ALREADY_ACTIVATED, 409 TRIAL_ACTIVATION_UNAVAILABLE, 503 TRIAL_ACTIVATION_RETRY. The ceiling is 3 requests per hour per account.

Before showing the activation step, read activation.marketTrial.available on GET /v1/cowork/state. It is a forecast: false is final, true means offering is fine but does not promise success, so keep handling a refusal at activation time. In regions on the tariff access model this trial does not exist as a product: the pre-check answers region_not_supported and the call itself refuses with 409 TRIAL_ACTIVATION_UNAVAILABLE.

FIX-0813-11: transient errors no longer close the trial for good

Before

Every account carried a counter of failed trial activations, and it advanced on ANY error — including the ones Bitrix24 never ruled on: the request did not reach it, it answered with an internal error, or our own authorization failed. Once the counter reached its ceiling the account got 409 TRIAL_ACTIVATION_UNAVAILABLE on every further request, with nothing to bring it back. Meanwhile 503 TRIAL_ACTIVATION_RETRY invited a retry — so the advice led straight into the trap where a run of network failures cost the account its one-time trial.