Unstick the channel

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

Recovers a stuck synchronous command channel on the server: releases the server-side operation lock and bounces the agent tunnel. The virtual machine is not rebooted.

Use this recovery for a confirmed leaked synchronous exec mutex after independently confirming the server is idle. Before acting on EXEC_BUSY, read the server operations with kind=exec and their outcomes. This endpoint does not cancel independent standalone durable jobs or clear their admission gate, even with force=true. For a confirmed synchronous leak, respect Retry-After when present, then use this guarded endpoint; unconditional lock deletion comes last, after the idle-state check. On STANDALONE, a running durable job keeps the execution channel busy after 202 releases the platform lock. Poll its operation; an unknown outcome needs support and independently confirmed full termination. Missing autoExpiresInSeconds does not prove a leaked mutex. Tunnel recovery and lock deletion do not clear durable admission. Galaxy commands run synchronously with a 600-second limit and share the host channel across all applications and deploys; your own operation list may not show another application’s job, so an empty list does not prove the host is idle.

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 — read the previous operation before retrying')
}

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 override the operation-lock guard, send the same request with ?force=true in the query string. This can interrupt synchronous execution; it does not cancel an independent standalone durable job or clear its admission gate.

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

For the full list of common API errors, see Errors.

Known specifics

• The lock check observes the current state. A shared operation lock normally blocks the request. However, if the lock holder record has exceeded its TTL and belongs to a command (op: exec), the request proceeds: the channel is reset, the tunnel is bounced, and the response is 200. An expired lock holder record for a deploy still blocks the request because a legitimate deploy can outlive 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 synchronous command. Bouncing the tunnel makes the agent terminate the stuck synchronous 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. Standalone durable jobs run independently; reconnecting does not prove they stopped or clear their admission gate.

• 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" — read the previous operation outcome before deciding whether to retry.

See also

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