Unstick the channel

POST /v1/infra/servers/:id/unstick

Forcibly frees the command execution channel on the server: releases the server-side operation lock and bounces the agent tunnel. The virtual machine is not rebooted.

This is the recovery path after the 409 EXEC_BUSY refusal returned by Run a command and by a deploy. The normal order puts this call FIRST: retries at the Retry-After interval, then unsticking the channel — it is guarded, so while a lock is still observed it answers 409 OPERATION_IN_PROGRESS, and it clears a lock by itself only when that lock is an exec mutex past its own TTL. The unconditional Release a stuck lock comes after it, and only once the server is independently confirmed idle — by its state and its logs.

Parameters

The request body is empty.

Examples

curl — personal key

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/unstick

curl — OAuth application

curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/unstick

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/unstick`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (!body.success) {
  console.error(body.error.code, body.error.message)
} else if (!body.data.reconnected) {
  console.log('The agent is still reconnecting — retry your command in a few seconds')
}

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/unstick`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

To unstick while an operation is running, send the same request with ?force=true in the query string.

Response fields

Response example

{
  "success": true,
  "data": {
    "backendLockReleased": true,
    "agentBounced": true,
    "reconnected": true
  }
}

Error response example

404 — the server was not found:

{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• The lock check observes the current state. A held shared operation lock keeps the refusal, but not every one does: when the holder record outlived its own TTL and it was a command (op: exec), the call goes through — the channel is reset, the tunnel bounced, the answer is 200. The same expired record for a deploy does NOT lift the refusal: a legitimate deploy outlives its TTL. The check does not reserve the channel: an operation may start afterwards, and some operations may run without a shared lock when the database is unavailable. Absence of a refusal does not guarantee that no commands are running.

• What happens to the stuck command. Bouncing the tunnel makes the agent terminate the stuck command's process group and connect again. The application service is not restarted, the files on disk are untouched, and the agent is not reinstalled — unlike Repair the tunnel, which reinstalls the agent outright.

• Unsticking does not wake a sleeping server. If the server is in sleeping status or waking is blocked for it, there is no tunnel and nothing to bounce: the platform releases the server-side lock and answers with success and agentBounced: false.

• The reconnect wait window is short and does not change the outcome. The platform watches the tunnel for a few seconds after the bounce and answers without waiting any longer. The agent reconnects on its own, so reconnected: false means "not seen yet" rather than "did not come back" — retry your command a few seconds later.

See also

• Run a command
• Release a stuck lock
• Repair the tunnel
• Full application deploy