#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 running but blackholeStatus is stuck in DISCONNECTED or WAITING — that is, the tunnel agent does not connect. The procedure goes through the serial console (bypassing the firewall) and includes: SSH-key injection → SSH connection → a full reinstall of the agent with the current version → waiting for reconnection. It takes up to 2 minutes; 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 get 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's timeout). 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 its actual purpose: the tunnel genuinely failing 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.
• 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.

#See also

• Repair status — GET /v1/infra/servers/:id/repair-status — progress of the current operation.
• Refresh status — check whether blackholeStatus recovered after the repair.
• Get server — check blackholeStatus and status.
• Reboot server — an alternative if repair did not help.

#Repair status

GET /v1/infra/servers/:id/repair-status

Returns the progress of a background tunnel repair started via POST /repair. Used for periodic polling: the client sees the current step (wake / serial_console / ssh_install / connect / …), the final status (running / done / failed), and, in case of an error, the error field. Completed records are cleared automatically after 10 minutes.

#Parameters

#Examples

#curl — personal key

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

#curl — OAuth application

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

#JavaScript — personal key

// Progress polling loop
while (true) {
  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()

  if (data.status === 'idle') { console.log('Repair not started'); break }
  if (data.status === 'done')  { console.log(`Done, step: ${data.step}`); break }
  if (data.status === 'failed'){ console.error(`Error at step ${data.step}: ${data.error}`); break }

  console.log(`Step: ${data.step}`)
  await new Promise(r => setTimeout(r, 10000))
}

#JavaScript — OAuth application

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

#Response fields

For status: "idle", only the status field is returned; the remaining fields are absent.

#Response example

Repair not started:

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

Repair in progress, agent installation step completed:

{
  "success": true,
  "data": {
    "status": "running",
    "step": "connect",
    "agentVersion": "1.2.3",
    "wasSlept": false,
    "startedAt": 1745312400000
  }
}

Repair failed:

{
  "success": true,
  "data": {
    "status": "failed",
    "step": "ssh_install",
    "agentVersion": null,
    "wasSlept": false,
    "error": "SSH connection refused",
    "startedAt": 1745312400000
  }
}

#Error response example

404 — server does not exist:

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

#Errors

Full list of common API errors — Errors.

#Known specifics

• Step execution order: wake (if the server is sleeping) → serial_console (inject the SSH key via the Bitrix24 Cloud serial console) → ssh_install (SSH connection and agent reinstall: download the binary, write the configuration, start the service) → connect (wait for the agent to connect to the Gateway) → iptables (restore the firewall for BLACKHOLE) → cleanup (return to sleeping if the server was sleeping) → done.
• Right after POST /repair the status is already running, not idle. The status is set to running synchronously when the repair starts, so the very first repair-status poll (even milliseconds later) sees running. Previously there was a brief window where a poll could see idle and the poll loop exited prematurely — that window is now gone.
• TTL of completed records — 10 minutes. After that, a repeat poll returns idle. If you need to confirm the result after the TTL, look at blackholeStatus in GET /v1/infra/servers/:id — if it is CONNECTED, the repair worked.
• Concurrent repair is impossible — there is an in-memory repairingServers lock at the service level. A repeat POST /repair on a server with a repair already in progress is handled correctly: the second call does not start a new procedure.

#See also

• Repair the tunnel — POST /v1/infra/servers/:id/repair — start a repair.
• Get the server — check the resulting blackholeStatus.
• Refresh status — force a provider poll after the repair.