API changes: August 31, 2026

← Changelog · August 2026

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 account'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-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 Bitrix24 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 Bitrix24 account 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 is no longer included — the platform mints the webhook automatically once a Bitrix24 account 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 Bitrix24 account 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.