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 WAITING — 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 was needed — see "Known specifics"); the call itself returns immediately and does not wait for completion. Track the progress via GET /repair-status.

This is not a way to clear EXEC_BUSY. /repair is a full reinstall of the tunnel agent: live processes started via /exec are interrupted along with their side effects (for example, an open COPY transaction in an external database will hang and hold its locks until that side times out). If the server responds with 409 EXEC_BUSY, release the lock with DELETE /v1/infra/servers/:id/lock — the agent and running processes are left untouched. Keep /repair for the case it is meant for: the tunnel genuinely fails to connect.

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, SSH through the iptables of a BLACKHOLE server is unavailable. The Bitrix24 Cloud provider's serial console bypasses the firewall at the hypervisor level and lets you 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, 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. 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), a BLACKHOLE one stays BLACKHOLE.
• How to unblock REPAIR_BLOCKED. If the server is marked preventWake (billing freeze, an expired trial, an admin block) — first resolve the cause (top up the balance, upgrade the plan), 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.

See also

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