Repair tunnel

POST /v1/infra/servers/:id/repair

Starts a background repair of the Black Hole tunnel through the cloud provider's serial console. Use it when the virtual machine is in the running status, but blackholeStatus is stuck in DISCONNECTED or NONE — that is, the tunnel agent is not connecting. The procedure goes through the serial console (bypassing the firewall) and includes: injecting an SSH key → connecting to the machine → fully reinstalling the agent at the latest version → waiting for it to reconnect. It takes up to 2 minutes (up to 4 minutes if the fallback install path is needed — see "Known specifics"); the call itself returns immediately and does not wait for completion. Track the progress via GET /repair-status.

Read the operation before repairing a busy channel. /repair reinstalls the tunnel agent and can interrupt live synchronous /exec commands and their side effects, including external database transactions. Standalone durable jobs execute independently: repair or a tunnel bounce does not guarantee their termination. For EXEC_BUSY, first read the server operations with kind=exec and their outcomes. Use guarded /unstick only for a confirmed leaked synchronous mutex after independently confirming idle state. DELETE /lock remains the final lock-recovery step after that check. Use /repair when the tunnel genuinely fails to connect; it does not serve as cancellation or permission to resend a command. 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/repair

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/repair

JavaScript — personal key

// Start the repair and poll the status periodically
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/repair`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

while (true) {
  await new Promise(r => setTimeout(r, 10000))
  const res = await fetch(
    `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/repair-status`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
  )
  const { data } = await res.json()
  console.log(`Step: ${data.step ?? data.status}`)
  if (data.status === 'idle' || data.status === 'completed' || data.status === 'failed') break
}

JavaScript — OAuth application

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

Response fields

Response example

{
  "success": true,
  "data": { "status": "started" }
}

Error response example

409 — repair blocked (for example, the server is marked preventWake=true):

{
  "success": false,
  "error": {
    "code": "REPAIR_BLOCKED",
    "message": "Repair blocked: server prevents wake"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• Why the serial console, not SSH. When the agent is not connected, a BLACKHOLE server's iptables rules block SSH. The Bitrix24 Cloud provider's serial console bypasses the firewall at the hypervisor level and makes it possible to inject an SSH key into an already-running virtual machine without rebooting it.
• Two agent-install paths. By default the agent is reinstalled over inbound SSH — that is the fast path. When inbound SSH is unavailable (port 22 does not answer, the stored IP is stale, cloud firewall rules block it, sshd is down), the procedure installs the agent out-of-band over the same serial console: the agent only needs an OUTBOUND connection to the gateway, so inbound access is not required for a reinstall. A machine without a public IP uses the serial console directly; where there is none, the repair ends with the REPAIR_NO_TRANSPORT code. The fallback attempt adds up to two minutes to an already-failing call; if both paths fail, the error field of GET /repair-status carries both reasons joined by ; serial fallback:.
• Idempotent. The procedure runs a full cycle (stop the agent → download a fresh binary → clean configuration → start) and is safe for a healthy server — it cannot do harm. A repeated call during an ongoing repair simply returns 409 / the same started, breaking nothing.
• The server mode is preserved. An OPEN server stays OPEN (iptables is not touched), and a BLACKHOLE server stays BLACKHOLE.
• How to unblock REPAIR_BLOCKED. If the server is marked preventWake (for example, a frozen balance, expired platform access, an administrative block), first resolve the cause (top up the balance or restore platform access), then retry /repair.
• GUEST_NOT_BOOTING cannot be fixed by a repair. The marker is visible in advance in the provisionErrorCode field of the server record — GET /v1/infra/servers/:id. Read it before the call: for such a machine, repair is refused, and the only action left is to delete the server and create a new one.
• A full disk stops the repair. GET /repair-status returns status: "failed", and the error text starts with DISK_FULL:. The same code appears in the provisionErrorCode field of the server record — GET /v1/infra/servers/:id. Repeating the repair helps only once disk space has been freed. A successful repair clears the code.
• REPAIR_NO_TRANSPORT — the platform has no channel to the server. When the refusal is known up front (the record has no key to sign in with), POST /repair answers 422: recreate such a server or restore it from a backup if one exists. When the platform could not get onto the server during the repair itself, GET /repair-status returns status: "failed", and the error text starts with REPAIR_NO_TRANSPORT: followed by the sentence: The platform could not reach this server to reinstall the agent: it has no working SSH path and no console access. Retry the repair later; if it keeps failing, contact support. Retry the repair later, and contact support if the refusal persists. After such a refusal the repair does not put a server it woke back to sleep: the server stays on until its idle-sleep setting stops it or you put it to sleep yourself. Other repair failures carry their own error text. While the server is still starting up, the platform retries the sign-in; an authentication failure refuses the repair at once.

See also

• Repair status
• Refresh status
• Get server
• Reboot server