For AI agents: markdown of this page — /docs-content-en/infra/lifecycle/repair-status.md documentation index — /llms.txt

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

Parameter In Type Required Description
id path string (UUID) yes Server ID

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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

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

javascript 
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

Field Type Description
success boolean Always true on success
data.status string idle (repair not started or cleared by timeout), running (in progress), done (succeeded), failed (failed)
data.step string Current/last step: wake, serial_console, ssh_install, connect, iptables, cleanup, done
data.agentVersion string | null Version of the installed agent (filled in at the ssh_install step)
data.wasSlept boolean Whether the server was sleeping when the repair started (if so, it returns to sleeping after done)
data.error string Error text, if status: "failed". If the agent failed to install because the disk is full, the text starts with DISK_FULL:. If the platform could not get onto the server (it cannot be reached over SSH and has no console access), the text starts with REPAIR_NO_TRANSPORT:. 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 failures carry their own text. Details are in Repair tunnel
data.startedAt number Repair start timestamp (Unix milliseconds)

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

Response example

Repair not started:

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

Repair in progress, agent installation step completed:

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

Repair failed:

JSON 
{
  "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:

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

Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY The key is not recognized — no such key exists on the platform
403 SERVER_ROLE_FORBIDDEN You are on this server's development team with the Developer role, and this operation is open to the Administrator role. error.hint carries your role, the required threshold and the list of calls that are open to you. Role breakdown — List servers
404 NOT_FOUND Server does not exist, was deleted, or belongs to another API key while you are not on its development team
429 RATE_LIMITED The platform-wide request limit was exceeded

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 mode) → 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