API changes: October 1, 2026

← Changelog · October 2026

NEW-1001-1: Manage CRM to-dos and activity deadlines

Create and update CRM to-dos through POST /v1/activity-todos and PATCH /v1/activity-todos/:id. Any activity can now be completed, postponed, or have its deadline changed. Read and list activities through /v1/activities.

NEW-1001-2: read CRM forms

The Vibecode API provides GET /v1/crm-forms and GET /v1/crm-forms/:id: a form list and safe form-field details. Reading requires a key with the crm scope; captcha and integration settings are excluded.

NEW-1001-3: Cross-entity CRM and requisite lookup

Added POST /v1/crm/search to search across CRM types and report tariff limits, and POST /v1/requisites/lookup to obtain requisite fields from a number and preset.

BC-1001-4: machine file links require a Vibecode API key

Old format supported until: not provided

Before

Machine addresses in CRM file fields and Bitrix24 documents granted downloads without a Vibecode API key.

After

The urlMachine, downloadUrlMachine, pdfUrlMachine, imageUrlMachine, and downloadMachine field names remain, but available files now link to the Vibecode API. The file cannot be opened without X-Api-Key. A document or template without a verified route has no machine field. Browser links remain available. Downloads from a self-hosted portal over HTTP now return 502; configure HTTPS for file and credential transport.

What integrators should do

Pass the same key with the required scope when following a machine link. See CRM files, CRM documents, and templates.

NEW-1001-5: download CRM files and documents through the Vibecode API

CRM field files are available through the download route; generated CRM documents can be downloaded as DOCX, PDF, and a preview image. REST templates can also be downloaded with a Vibecode API key. READONLY keys with the required scope are accepted.

NEW-1001-6: CRM payments with product positions and delivery reads

Added /v1/crm-payments and /v1/crm-deliveries under the crm scope. A payment can be created directly for a deal; Bitrix24 creates the linked order. Product positions are added separately and Bitrix24 recalculates the amount. The paid mark may trigger Bitrix24 account automation.

NEW-1001-7: create and manage CRM documents through the Vibecode API

A document for a deal or another CRM record can now be created from a template, read, updated, deleted, and uploaded through the CRM document routes. A separate action enables or disables a public URL. File downloads use authenticated Vibecode API routes.

NEW-1001-8: file size refusal on upload carries a hint

The 413 IMAGE_TOO_LARGE response of POST /v1/feedback/attachments and the 413 STORAGE_UPLOAD_TOO_LARGE response of POST /v1/storage/objects/upload gained an optional error.hint field with English text on what to do next: shrink the image or switch to multipart upload. The error.message of IMAGE_TOO_LARGE now names the 10 MB cap. Codes and statuses are unchanged, and clients that read only error.code need no changes.

FIX-1001-9: Cowork key no longer refused to a box service account

Before

Cowork key rotation and PATCH /v1/keys/:id could return 403 COWORK_BOX_SERVICE_ACCOUNT_DENIED when the key owner signed in from a self-hosted Bitrix24 without a Bitrix24 account.

After

Box service accounts no longer exist, so rotation and PATCH /v1/keys/:id no longer return 403 COWORK_BOX_SERVICE_ACCOUNT_DENIED.

NEW-1001-10: CRM document templates are available through the Vibecode API

New routes list, create, update, and delete CRM templates, find templates for a specific record, and download the source DOCX using a Vibecode API key with the crm scope.

NEW-1001-11: cause, action and a text for a person in refusals for a key's scope

Refusals for a scope missing on the API key itself carry new optional fields: error.cause with the value key_scope_missing, error.requiredScope — the missing scope, error.keyScopes — the key's scopes on this request, error.fix, error.hint and error.userMessage — a text for a person that can be shown as is. The fields arrive in 403 INSUFFICIENT_SCOPE of the /v1/cowork/* routes, in 403 INFRA_SCOPE_REQUIRED, in 403 SCOPE_NOT_ALLOWED of a batch request and in 403 SCOPE_DENIED of entity routes (including their batch and aggregate calls and include), timeline items and open channels. error.fix.action is edit_key_scopes when the scope can be added to the key in the cabinet, reissue_key for a key of an OAuth application from the Applications section, and none otherwise. A key issued through Partner Connect never gets edit_key_scopes: its scope set records the user's consent, and the supported path is re-consent, which the application runs. In a batch request the entries of data.errors with the code SCOPE_NOT_ALLOWED carry cause, requiredScope, fix and hint, while keyScopes and userMessage arrive only in the 403 response itself. 403 SCOPE_DENIED of the business process editor, when Bitrix24 itself refused the scope, carries error.cause = b24_scope. The code, status and error.message are unchanged. Details — Authorization, keys and permissions.

FIX-1001-12: a Bitrix24 scope refusal no longer calls a cabinet key a platform key

Before

Responses 403 BITRIX_ACCESS_DENIED and 422 BITRIX_ERROR with error.cause = b24_scope, for some keys created in the cabinet and for keys issued through Partner Connect, carried an error.hint saying the platform manages the key and its scopes are not edited from the cabinet. Keys the platform issued for a specific purpose (Cowork/Code, server maintenance, collaborator access) got the same statement, although their scopes can be edited in the cabinet.

After

error.fix.action is still none. error.hint says it as it is: for some keys created in the cabinet the response does not know whether the key was issued through Partner Connect — the scope set of such a key records the user's consent — so it does not advise adding the scope to the key; for a key the platform issued for a specific purpose, it says that whether adding the scope would take effect is not determined. The codes, statuses and error.message are unchanged. Details — Authorization, keys and permissions.

Impact on integrators

No action is required: error.fix is unchanged, only the text of error.hint changes.

BC-1001-13: Human approval for wider application access

Old format supported until: not provided

Before

Machine operations could widen application access immediately, without separate human approval:

• PATCH /v1/infra/servers/{id}/access-policy — change the access policy.
• POST /v1/infra/servers/{id}/access — add a user or department.
• DELETE /v1/infra/servers/{id}/access/{accessId} — remove an entry when restoring other grants widens the audience.
• POST /v1/infra/servers/{id}/access-tokens — issue a token.

After

Audience changes on protected Bitrix24 accounts require human approval for machine requests that widen access. The first request returns 409 AUDIENCE_APPROVAL_REQUIRED without changing access; its details provide the review URL and exact retry operation. Retry using the same credential and approvalId after human approval. Token mint retries use the frozen absolute expiresAt, with no ttlSeconds recalculation. Requesting credentials can recover or cancel their own proposals; they cannot approve them.

Deploy and redeploy preserve audience, grants and credentials. Read operations, proven reductions and bodyless bearer refresh continue under their existing authorization rules. PATCH /v1/infra/servers/{id}/mode: machine requests for OPEN are refused before network work; direct exposure uses the verified human cabinet.

What integrators should do

Handle 409 AUDIENCE_APPROVAL_REQUIRED by showing the review URL to a human and waiting for approval. Then retry the exact operation with approvalId and the original credential; token retries must retain the original absolute expiresAt. Replace machine OPEN requests with a human action in the cabinet. For access-entry deletion, pass approvalId in the query: DELETE /v1/infra/servers/{id}/access/{accessId}?approvalId=APPROVAL_ID. Automatic retries without approval do not widen access. No support window for the previous behavior is provided.

BC-1001-14: a multifield row with an id is refused on every write door

Old format supported until: not provided

Before

An object with an id field inside phone, email, web or the raw fm[] array was accepted and forwarded to Bitrix24. On update (PATCH /v1/contacts/{id}, plus leads and companies, batch calls and /v1/batch) Bitrix24 ignores id and adds a SECOND row: the call answered 200 and the contact ended up with a duplicate phone. An attempt to delete a row with { "id": 11, "value": "" } answered 200 and did nothing. On create (POST /v1/contacts, batches, import) the id was silently discarded.

After

Such a request is refused before Bitrix24 is called: 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The message differs per door: on update it explains that Bitrix24 ignores the id and would append a duplicate, on create that Bitrix24 assigns multifield row ids itself. The check covers phone, email, web and the raw fm[] on single calls, on entity batch calls, on /v1/batch and on import.

What integrators should do

Send a multifield row without an id — that appends a new value. Replacing or deleting one phone or email through this API is not possible: edit the record in the Bitrix24 interface.

NEW-1001-15: CRM dictionaries, mode and currency localizations

Added GET /v1/crm-enums/owner-types, GET /v1/crm-enums/address-types, GET /v1/crm-settings/mode, GET /v1/statuses/entity-types, GET /v1/requisite-presets/countries and GET /v1/currencies/base. Use them to select entity and address types, status dictionaries and preset countries, and discover whether leads are enabled.

GET, PUT and DELETE /v1/currencies/:id/localizations read, set and remove currency display settings by language. GET /v1/currencies/:id/localizations/fields lists supported camelCase fields. Empty input and unknown fields are rejected before Bitrix24; currency existence is checked before localization access, writes and deletions are verified by reading back. Base-currency changes are not added.

NEW-1001-18: recentCallsDataSince field in GET /v1/ai/usage

The GET /v1/ai/usage response now carries data.recentCallsDataSince — the per-call history boundary in ISO 8601. Per-call history is kept for at least 35 days: if the key is older than that boundary, the field carries its date and recentCalls holds no calls before it — an empty array then means "no calls since the boundary". null means the key's whole history is available. The totals, byModel and byScope counters are not affected by the boundary; all other response fields are unchanged.

BC-1001-19: changing the mode of Cowork/Code seat keys through V1 and re-issuing a key wider than the caller are refused with 403

Old format supported until: not provided

Before

PATCH /v1/keys/:id with a mode field on a Cowork/Code desktop key and on an external agent key billed to a Cowork/Code subscription answered HTTP 200 and changed the mode of that single key row. POST /v1/cowork/applications/:id/key on an application whose slot key is wider than the caller answered HTTP 201 and minted the new key in the previous, wider mode.

After

The mode of a Cowork/Code key is the mode of the seat — the pair of a person and a Bitrix24 account — shared by all its devices. PATCH /v1/keys/:id changing mode on a Cowork/Code desktop key answers 403 COWORK_SEAT_KEY_MODE_CABINET_ONLY. On an external agent key a request for a mode wider than the seat answers 403 COWORK_KEY_MODE_ABOVE_SEAT, and within the seat the edit works as before. A request carrying the SAME mode, sent for a rename, is not a change and passes: the response remains HTTP 200. POST /v1/cowork/applications/:id/key on an application whose slot key is wider than the caller answers 403 KEY_ROTATE_WIDER_THAN_CALLER instead of issuing a key wider than the caller.

What integrators should do

Change the seat mode by editing the Cowork/Code desktop key in the "API Keys" section of your Vibecode account: the change shows what narrows along with the seat. On COWORK_KEY_MODE_ABOVE_SEAT, widen the seat first, then repeat the edit of the external agent key. On KEY_ROTATE_WIDER_THAN_CALLER, re-issue the application key in your Vibecode account.

BC-1001-20: keys issued by a Cowork/Code seat are no wider than the seat mode

Old format supported until: not provided

Before

POST /v1/cowork/deploy-key minted the deploy key in the read-write mode whatever the mode of this pair's desktop keys. POST /v1/apps under a deploy key with an explicit mode issued the paired application key in the requested mode.

After

Keys issued by a Cowork/Code seat are no wider than the seat mode, the seat being the pair of a person and a Bitrix24 account. The deploy key comes out in the narrower of the calling key mode and the seat mode. POST /v1/apps under a seat key, as a deploy key is, issues the paired key no wider than the seat mode: an explicit request wider than the seat alone issues the key in the seat mode without a refusal, and the response remains HTTP 201. No window with the old behavior is provided: the seat ceiling is a boundary its owner chose, and a window would cancel it.

What integrators should do

If the integration needs a deploy key or an application key that can write while the seat is read-only, widen the seat: change the mode of the Cowork/Code desktop key in the "API Keys" section of your Vibecode account. The accessMode field of the POST /v1/cowork/deploy-key response names the mode of the minted deploy key.

NEW-1001-21: POST /v1/cowork/deploy-key names the mode of the minted key

The POST /v1/cowork/deploy-key response carries a new accessMode field — the mode of the minted deploy key. It is never wider than the calling key and never wider than the Cowork/Code seat mode of this pair: the deploy key is the seat's instrument, so a read-only seat gets a read-only deploy key. The existing response fields are unchanged.

FIX-1001-22: an application and an empty-slot key are issued in the caller's mode instead of 403

Before

POST /v1/apps without a mode field under a read-only key on an account whose policy is read-write answered 403. GET /v1/cowork/applications/defaults showed the account policy mode alone, although creation issued a key no wider than the caller. POST /v1/cowork/applications/:id/key on an empty slot under a read-only policy answered 403 KEY_POLICY_READONLY_REQUIRED.

After

POST /v1/apps without mode issues the application in the narrower of the policy mode and the calling key mode; an explicit request wider than the caller still answers 403 WRITE_BLOCKED_READONLY_KEY. GET /v1/cowork/applications/defaults shows the mode creation will actually issue. Issuing into an empty slot mints the key in the narrower of the policy mode and the caller mode instead of 403; on this endpoint KEY_POLICY_READONLY_REQUIRED remains only for a development-team member key that would be wider than the policy. While the write block for read-only keys is in force (it is by default), for such a calling key POST /v1/cowork/applications and POST /v1/cowork/applications/:id/key themselves answer 403 WRITE_BLOCKED_READONLY_KEY before any other check, so for such a key defaults shows the ceiling, not a promise of issuance.

FIX-1001-23: a third-party agent key is no longer told to obtain a deploy key

Before

GET /v1/me called with a Cowork/Code subscription key issued for third-party agent software named the POST /v1/cowork/deploy-key endpoint with the steps to obtain a deploy key in its deployment block and returned the deployment.deployKeyEndpoint field, and the notes of the server and application slots in capabilities pointed to the same endpoint. Such a key got the same advice in error.details.requiredAction of the 403 INFRA_FORBIDDEN_FOR_COWORK_KEY refusal, and GET /v1/guide advised obtaining a deploy key in infraApi.coworkKeyNotice with no exception. The endpoint itself answers such a key with 403 COWORK_HARNESS_KEY_FORBIDDEN.

After

For such a key, deployment.howToDeploy, the slot notes in capabilities and error.details.requiredAction of the 403 INFRA_FORBIDDEN_FOR_COWORK_KEY refusal say that a deploy key is never issued to it (403 COWORK_HARNESS_KEY_FORBIDDEN) and that applications are delivered from the Cowork/Code desktop app or with an ordinary key carrying the vibe:infra scope. The deployment.deployKeyEndpoint field is absent for such a key. infraApi.coworkKeyNotice and the endpoint description in the guide carry the same exception for a third-party agent key. The /v1/me and /v1/guide responses remain HTTP 200, the code and status of the 403 INFRA_FORBIDDEN_FOR_COWORK_KEY refusal are unchanged, and for other keys the texts are the same as before.

FIX-1001-24: rotatable and rotateBlockedReason account for the calling key mode

Before

The key block of an application card (GET /v1/applications, GET /v1/applications/:id) computed rotatable without the calling key mode: the card promised rotatable: true where POST /v1/cowork/applications/:id/key answered with a refusal.

After

rotatable and rotateBlockedReason account for the calling key mode: rotatable becomes false, and rotateBlockedReason carries WIDER_THAN_CALLER when the slot key is wider than the caller and WRITE_BLOCKED_READONLY_KEY when the calling key does not change data and the write block for such keys is in force. The response remains HTTP 200; a reason unknown to the client reads as "cannot be replaced, reason unknown".

FIX-1001-25: updating a to-do no longer overwrites concurrent edits

Before

PATCH /v1/activity-todos/:id with a field that has no Bitrix24 point method (for example, title or pingOffsets) sent the title, description, deadline, reminders and responsible user taken from a read made several Bitrix24 requests before the write. An edit made in that interval by another user or a parallel request was overwritten with the previous value. When the current responsible user could not be assigned again, such a PATCH failed even though the request did not contain a responsible user.

After

Values of the fields absent from the request are read immediately before the write. The responsible user is sent only when the request contains it. The successful response remains HTTP 200. The existing 422 ACTIVITY_UPDATE_NOT_APPLIED code is now also returned in a new case: after the write, a field absent from the request differs from the value read before it.

Impact on integrators

No action required. An edit saved to the to-do before the write started is normally kept when another field is patched. On a 422 ACTIVITY_UPDATE_NOT_APPLIED that mentions fields absent from the request, inspect the to-do: the write was applied, but one of those fields changed.

BC-1001-27: string parameters no longer accept arrays and objects

Old format supported until: not provided

Before

Some string parameters of public V1 endpoints implicitly converted arrays and objects to strings. This affected the sha256 filters, folder and department identifiers, the note-collection cursor, model, limits, event-subscription parameters, and the placement-handler PROTOCOL value.

After

Parameters declared as string or numeric scalars accept only matching scalar values. Arrays and objects receive the response defined by each endpoint or are treated as a missing optional parameter. The placement handler enables HTTP mode only for the string value PROTOCOL='0'.

What integrators should do

Send these parameters as single strings or numbers as documented. Do not use bracket query syntax or JSON arrays and objects in place of scalar values.

Affected endpoints: GET /v1/apps/:id/sources, GET /v1/infra/servers/:id/sources, POST /v1/files/:id/moveto, POST /v1/files/:id/copyto, POST /v1/folders/:id/moveto, POST /v1/folders/:id/copyto, POST /v1/humanresources/nodes/search, POST /v1/infra/servers/:id/event-subscriptions, GET /v1/note/collections, GET /v1/off-peak, GET /v1/mail/messages, POST /v1/bitrix-handler.

BC-1001-28: Disk file download links require a Vibecode API key

Old format supported until: not provided

Before

The downloadUrl field in Disk file responses and in chat file metadata held a Bitrix24 address with access to the Bitrix24 account that opened without a Vibecode API key.

After

The downloadUrl field keeps its name and, for a file with an identifier, points to GET /v1/files/:id/download. The file cannot be downloaded through it without X-Api-Key. A key with only the im scope also needs the disk or crm scope to follow the link from chat file metadata. The link to the file page in Bitrix24 (detailUrl) remains.

What integrators should do

Pass the same key when following downloadUrl. Replace Bitrix24 addresses stored from earlier responses with new ones from a repeated request.

NEW-1001-29: the application external API works with a server in the schedule run mode

A server in the schedule run mode is now admitted to the application external API ANY /v1/applications/:id/api/**, as long as its plan is not preemptible. The answer depends on the server state. A running server accepts the call — inside the windows of its work schedule and after a window ends, until it falls asleep after an idle period; such calls extend its running time, which the application owner pays for. A sleeping server outside a window answers with the new code 409 APP_API_OUTSIDE_SCHEDULE and a Retry-After header — the number of seconds until the next window starts; retry the call after that delay. When the delay cannot be computed (for example, the server's schedule was deleted), there is no such header, and retrying on a timer will not help — check the server's schedule. 503 APP_API_UNAVAILABLE goes to a server whose wake-up is blocked (for example, suspended over payment) and to a server that is neither running nor asleep outside a window: still waking up for a window, stopped, in an error state or still being created. The External API switch of such a server turns on while the server is running and its wake-up is not blocked. Solutions on such a server follow the same rule: while the server is running, publishing a solution contract and a solution call succeed; for a sleeping server outside a window, publishing does not go through and a solution call gets SOLUTION_UNAVAILABLE. Servers without a schedule are not affected. Details — Application external API.

BC-1001-30: Explicit refusal for duplicate and missing CRM bindings

Old format supported until: not provided

Before

POST of an existing deal or company contact binding returned the successful list; DELETE of a missing binding returned 204.

After

POST returns 409 RELATION_ALREADY_EXISTS when Bitrix24 returns false. DELETE of a missing binding returns 404 ENTITY_NOT_FOUND. The same behavior applies to the new contact/company and lead/contact bindings. Clients need to handle these statuses instead of the previous successful response.

What integrators should do

Handle 409 when adding a duplicate binding and 404 when removing a missing binding; use collection DELETE for idempotent clear-all.

NEW-1001-31: Contact company bindings, lead contact bindings and clear-all

GET / POST / PUT /v1/contacts/:id/companies and /v1/leads/:id/contacts; DELETE with /:relatedId removes one binding. Collection DELETE clears bindings for contacts, leads, deals and companies with 204. Existing single-object include=company and include=contact remain; companyBinding and contactBinding expand the full sets.

NEW-1001-32: status change reason in the server activity feed

server.status_changed events of GET /v1/infra/servers/{id}/activity gained an optional meta.reason field. Today it has one value, billing_freeze: the server was put to sleep by a balance freeze. Other status changes carry no such field; existing requests keep working as before.

NEW-1001-33: The pull_channel scope is available on enabled accounts

On accounts where Pull channel support is enabled, pull_channel can be selected when creating a key or application. Other accounts do not show the scope in the picker or add it to new keys.

NEW-1001-34: Contact and company call lists

Added GET /v1/call-lists, GET /v1/call-lists/:id, POST /v1/call-lists, PUT /v1/call-lists/:id, GET /v1/call-lists/:id/items and GET /v1/call-lists/statuses. PUT fully replaces participants and clears omitted webformId. Writes return id and skipped based on visible participant readback. Creation also creates a call activity; lists cannot be deleted through REST. Dates preserve the timezone-free value. Missing lists return 404 ENTITY_NOT_FOUND; Bitrix24 business refusals return 422 BITRIX_ERROR. READONLY keys receive 403 WRITE_BLOCKED_READONLY_KEY on writes.

NEW-1001-35: Recurring deals and immediate template exposure

Recurring deals: added /v1/recurring-deals with create, read, update, delete, fields, search and batch operations. POST /v1/recurring-deals/:id/expose creates a deal from a template and returns its ID and link. When configuring an ordinary deal, Bitrix24 creates a separate template copy; the response contains the actual dealId. Availability depends on the Bitrix24 plan.

FIX-1001-36: postponing a legacy task activity no longer returns a false 422

Before

POST /v1/activities/{id}/postpone for a legacy task activity (TYPE_ID=3) with a stale non-empty PROVIDER_ID returned 422 ACTIVITY_POSTPONE_NOT_APPLIED even though Bitrix24 moved the linked task deadline.

After

Such an activity is handled as a TASKS provider activity: the response is HTTP 200 with the re-read activity, and the activity time itself may stay unchanged. Other activities keep the check, and an unmoved time still returns 422 ACTIVITY_POSTPONE_NOT_APPLIED. See postponing an activity.

Impact on integrators

No action required. A workaround for the 422 on such activities is no longer needed.

NEW-1001-37: Upload chat files without immediate publication

The Vibecode API adds POST /v1/chats/:chatId/files/uploads to upload without a message, POST /v1/chats/files/uploads/status to check existence, POST /v1/chats/:chatId/files/uploads/discard to discard, and POST /v1/chats/:chatId/files/uploads/publish to publish several files in one message. Upload becomes available with Bitrix24 im 26.1500.0; before that release reaches a Bitrix24 account, the route returns 422 METHOD_NOT_YET_AVAILABLE. The existing POST /v1/chats/:chatId/files keeps its behavior.

FIX-1001-38: Your own DeepSeek or OpenAI-compatible provider key receives the model name without the catalog prefix

Before

A POST /v1/chat/completions request with model deepseek/deepseek-v4-pro or custom-openai-compat/<model> on your own provider key reached the provider with the catalog prefix, for example deepseek/deepseek-v4-pro. The provider does not know that name and rejected the call.

After

The provider receives the model name without its own provider prefix: deepseek-v4-pro, <model>. When a catalog model carries its own provider identifier, that identifier is still sent unchanged. openai/… models work as before.

NEW-1001-39: CRM sales-intelligence traces

POST /v1/crm-traces creates a visitor trace from a JSON object or JSON string. It can be bound to leads, deals, contacts, companies and quotes. Records are checked before creation. DELETE /v1/crm-traces/:id returns an idempotent 204 without confirming trace existence or removal of every binding. Requires the crm scope and a READWRITE key.

NEW-1001-40: GET /v1/me states the Bitrix24 data-write restriction on its own

For a read-only key, the GET /v1/me response carries a second restriction statement — a new root field portalWriteRestriction, about changing Bitrix24 data. It holds the code WRITE_BLOCKED_READONLY_KEY, the scope, the list of closed routes with a refusal condition on each entry and a link to the access mode page. Unlike the neighbouring writeRestriction, which covers platform writes, the field is present even when the platform write restriction is lifted: such a key does not change Bitrix24 data either way. For an application key, the placements block gets a note field — the embedding boundary for a key that may not write Bitrix24 data. For a personal READONLY key, portalEmbedding marks all embeddings, including LEFT_MENU, as unavailable even when the platform write restriction is lifted. PORTAL_READONLY keeps the left-menu item; READWRITE guidance is unchanged. More — Access mode.

FIX-1001-41: an immediate bot event re-poll after a refusal about the bot itself no longer gets 409

Before

If the bot changed between the start of a poll and its execution — for example, it was disabled or transferred to another key — GET /v1/bots/:botId/events returned the refusal (410 BOT_DISABLED, 403 BOT_ACCESS_DENIED or 404 BOT_NOT_FOUND) before the poll for that bot was considered finished. An immediate re-poll could get 409 BOT_EVENTS_BUSY instead of the same refusal.

After

The refusal is returned only after the poll finishes, so the re-poll immediately gets the same refusal. Error codes and statuses are unchanged, and the HTTP 200 response is unchanged too.

NEW-1001-42: Time control and work schedule members

Added time-control settings reads and updates, monthly absence reports, department employees and absence explanations at /v1/workday/time-control/*. An explanation requires the absence month and year. Settings affect the entire account; report IP addresses are personal data. /v1/workday/schedules/:id deletes a schedule and /v1/workday/schedules/:id/users includes an employee. DELETE /v1/workday/schedules/:id/users/:userId excludes an employee and removes future shift plans; other schedules remain unchanged. All operations require timeman.

NEW-1001-43: cause, action and a text for a person in SCOPE_DENIED of chat, CRM, calendar and other routes

403 SCOPE_DENIED for a scope missing on the API key itself, on the routes of activities, addresses, bookings, bots, the calendar, calls, call lists, catalog inventory documents and product images, chats, the CRM routes for payments, deliveries, documents, forms, search, card configuration, dictionaries and traces, Disk files and folders, document templates, the org structure, lists and mail, carries the same optional fields as the refusals of generated entity routes: error.cause with the value key_scope_missing, error.requiredScope — the missing scope, error.keyScopes — the key's scopes on this request, error.fix — the action, error.hint — an English explanation and error.userMessage — a text for a person that can be shown as is. When a route needs two scopes, error.requiredScope names the first missing one; when either of two is enough, it names the first one checked. The code, status and error.message are unchanged. Details — Authorization, keys and permissions.

NEW-1001-44: Order dictionaries and basket item properties

Added /v1/person-types, /v1/order-properties and /v1/basket-item-properties: read, create, update and delete with the sale scope. Search, static field schemas, aggregation and batch operations are available. Y/N flags are represented as booleans.

For order property PATCH, type, personTypeId and propsGroupId are read-only. Omitted fields, settings, payment/delivery links and ENUM variants are preserved. FILE with a stored defaultValue file requires an explicit replacement on PATCH (otherwise 400). settings accepts only an object; batch allows at most one update per order property per request. For basket item properties, basketId is read-only on PATCH. Writing a basket item property saves the entire order in Bitrix24.

NEW-1001-45: exchange an Atlas access token for a Cowork key and renew that key

POST /v1/connect/atlas/token exchanges an Atlas access token for a Cowork key. The request carries Authorization: DPoP <access> and a DPoP header with the device-key proof. The body requires client_id of the Cowork client. An optional device_id in a valid form binds the key to the installation and, after issuance, retires the previous keys of that installation. Any other device_id does not cancel issuance: the key is issued without an installation binding. Success is 200 and the body {api_key, expires_at}. expires_at is the token exp, in seconds.

POST /v1/connect/atlas/renew renews an already issued key with a fresh token of the same person and the same device. The same headers are joined by X-Api-Key holding the key to renew. The key string does not change. Success is 200 and the body {expires_at}: the expiry moves only forward, to the new token exp, and does not become shorter than the expiry already stored.

A rejected token or proof is 401. The WWW-Authenticate: DPoP header names error invalid_token or invalid_dpop_proof. The body of this refusal, and of the refusals below except the per-address frequency limit, is {error, error_description}. 400 invalid_request means client_id is missing on exchange or X-Api-Key is missing on renewal. 400 invalid_client happens only on exchange: the client is unknown, inactive, or not the Cowork client.

403 atlas_source_unsupported means the identity is not a person of a Bitrix24, or the Bitrix24 is not self-hosted. 403 atlas_portal_unknown means the token does not name a Bitrix24 this platform knows. 403 atlas_user_not_linked means this Bitrix24 user has no account on the platform yet. 403 atlas_user_unavailable carries details.reason: blocked, deleted, erasing, or member_gone. 403 atlas_identity_changed carries details.reason: atlas_subject_changed or portal_occupant_changed. 403 atlas_key_mismatch happens only on renewal: the key was issued to another identity or another device.

When key issuance itself refuses, the error field carries the same code the Connect device flow returns in code: 503 COWORK_DISABLED, 403 COWORK_KEY_GATED, 403 COWORK_HIDDEN (details.requestable says whether an access request can be filed), 403 ACCESS_DENIED, 403 COWORK_SUB_PAUSED, 403 COWORK_SUB_CANCELLED, 409 B24_USER_DELETED, 500 ISSUANCE_FAILED.

429 too_many_requests with a Retry-After header means one Atlas identity has made more than five exchanges in ten minutes. Renewal does not spend this budget. Separately, both addresses limit how often one client address may call them. Past the cap the response is 429 in the V1 envelope, error.code is RATE_LIMITED, and the response carries a Retry-After header. The effective value for the key is the x-ratelimit-limit header. The platform-wide cap is 30 requests per minute per address, and it is divided across replicas.

503 temporarily_unavailable with a Retry-After header means the issuer keys or the one-time proof check are temporarily unavailable.

NEW-1001-46: Shipments and shipment items

• /v1/shipments and /v1/shipment-items: create, read, search, update and delete order shipments and positions with sale scope.
• POST /v1/shipments/:id/ship and /unship: change the shipped mark and return the shipment after readback; warehouse accounting can deduct stock.
• Shipment PATCH preserves fields Bitrix24 resets when omitted. deducted is readonly; shipment batch is disabled to prevent data loss.

NEW-1001-47: cause, action and a text for a person in key scope refusals of the tasks, web search, users and other routes

403 SCOPE_DENIED of the notes, notifications, page publishing, performance review, feed, requisites, user fields, web search, Scrum, tasks, users, warehouses, workday, business process, workgroup, timeline log, recurring deal and CRM trigger routes carries the same optional fields as the refusals of generated entity routes: error.cause with the value key_scope_missing, error.requiredScope — the missing scope, error.keyScopes — the key's scopes on this request, error.fix — the action, error.hint — an English explanation and error.userMessage — a text for a person that can be shown as is. On this refusal the GET /v1/search/providers response also gained success: false, like every V1 error response. The code, status and error.message are unchanged. Details — Authorization, keys and permissions.

NEW-1001-48: connector endpoints for the Cowork desktop

The Cowork desktop gets three connector endpoints. GET /v1/connectors returns the connectors of the Bitrix24 account with the state for the employee and the number of actions waiting for confirmation. POST /v1/connectors/{slug}/access-requests files an access request. GET /v1/connectors/write-tickets/{id} returns the outcome of a write confirmation and the text the agent continues with. The endpoints accept only a Cowork device key; any other key gets 403 CONNECTOR_KEY_NOT_ALLOWED. Everything is behind the connectors flag: while it is off, the endpoints answer 404.