# API changes: October 1, 2026

[← Changelog](/docs/changelog) · [October 2026](/docs/changelog/2026-10)

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

Create and update CRM to-dos through [POST /v1/activity-todos](/docs/entities/activity-todos/create) and [PATCH /v1/activity-todos/:id](/docs/entities/activity-todos/update). Any activity can now be [completed](/docs/entities/activities/complete), [postponed](/docs/entities/activities/postpone), or have its [deadline changed](/docs/entities/activities/deadline). 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](/docs/recipes/crm-files), [CRM documents](/docs/entities/documents/crm-list), and [templates](/docs/entities/doc-templates/download).

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

CRM field files are available through the [download route](/docs/recipes/crm-files); generated CRM documents can be downloaded as [DOCX](/docs/entities/documents/download), [PDF](/docs/entities/documents/pdf), and a [preview image](/docs/entities/documents/image). [REST templates](/docs/entities/doc-templates/download) 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](/docs/entities/documents). 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](/docs/feedback/attachments) and the `413 STORAGE_UPLOAD_TOO_LARGE` response of [POST /v1/storage/objects/upload](/docs/storage/upload/direct) 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](/docs/entities/crm-document-templates) 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](/docs/errors/auth#scope_denied-403).

### 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](/docs/errors/auth#bitrix_access_denied-403).

**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](/docs/infra/access/access-policy) — change the access policy.
- [POST /v1/infra/servers/{id}/access](/docs/infra/access/access-add) — add a user or department.
- [DELETE /v1/infra/servers/{id}/access/{accessId}](/docs/infra/access/access-delete) — remove an entry when restoring other grants widens the audience.
- [POST /v1/infra/servers/{id}/access-tokens](/docs/infra/access-tokens/create) — 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](/docs/infra/access/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}](/docs/entities/contacts/update), 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](/docs/entities/contacts/create), 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`](/docs/ai/consumption/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](/docs/keys-auth/me) called with a Cowork/Code subscription key issued for third-party agent software named the [POST /v1/cowork/deploy-key](/docs/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](/docs/keys-auth/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](/docs/entities/activity-todos/update) 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](/docs/source-storage/versions), [GET /v1/infra/servers/:id/sources](/docs/source-storage/servers), [POST /v1/files/:id/moveto](/docs/entities/files/moveto), [POST /v1/files/:id/copyto](/docs/entities/files/copyto), [POST /v1/folders/:id/moveto](/docs/entities/folders/moveto), [POST /v1/folders/:id/copyto](/docs/entities/folders/copyto), [POST /v1/humanresources/nodes/search](/docs/humanresources/nodes/search), [POST /v1/infra/servers/:id/event-subscriptions](/docs/infra/event-subscriptions/create), [GET /v1/note/collections](/docs/note/collections/list), [GET /v1/off-peak](/docs/ai/consumption/off-peak), [GET /v1/mail/messages](/docs/mail/messages/list), [POST /v1/bitrix-handler](/docs/infra/app-runtime).

### 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`](/docs/entities/files/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](/docs/chats/files/file-get). 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](/docs/infra/lifecycle/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](/docs/infra/work-schedules) 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](/docs/applications/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](/docs/entities/activities/postpone).

**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](/docs/chats/files/upload-to-folder) to upload without a message, [POST /v1/chats/files/uploads/status](/docs/chats/files/upload-status) to check existence, [POST /v1/chats/:chatId/files/uploads/discard](/docs/chats/files/upload-discard) to discard, and [POST /v1/chats/:chatId/files/uploads/publish](/docs/chats/files/upload-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](/docs/chats/files/upload) 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](/docs/entities/crm-traces/create) 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](/docs/entities/crm-traces/delete) 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](/docs/keys-auth/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](/docs/keys-auth/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](/docs/errors/auth#scope_denied-403).

### 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](/docs/errors/auth#scope_denied-403).

### 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.