Get a server

GET /v1/infra/servers/:id

Returns details of a single server by ID. For a full owner card, the endpoint automatically polls the cloud provider when the stored status is provisioning, or when the IP is absent and the server has an external ID. A deleted server (status: "deleted") is not accessible: a 404 is returned.

The card has three shapes. The managing key gets the full object. An application key gets the same shape without an access block for the server bound to its application, except for a GALAXY host, even when the server row is assigned to another application key. A member of the server's development team gets 200 with a shortened card. If the galaxyId of a live Galaxy application managed by the current key points to a live shared host in the same Bitrix24 account, that host arrives as a safe read-only projection with access.via: "galaxy-reference". The shapes and fields are broken down in List servers.

Parameters

Examples

curl — personal key

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/e765edfc-ba0a-43de-b8ea-838dd872c522

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

JavaScript — personal key

// Poll the server until it is ready
async function waitReady(serverId) {
  while (true) {
    const res = await fetch(
      `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
      { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
    )
    const { data } = await res.json()
    if (data.access?.via === 'galaxy-reference') {
      throw new Error('Use the Galaxy application ID, not the host ID, to wait for readiness')
    }
    if (data.status === 'running' && data.blackholeStatus === 'CONNECTED') {
      return data
    }
    if (data.status === 'error') {
      throw new Error(`Server in error state: ${data.id}`)
    }
    await new Promise(r => setTimeout(r, 10000))
  }
}

JavaScript — OAuth application

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

Response fields

Full response example

{
  "success": true,
  "data": {
    "id": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "status": "running",
    "provider": "bitrix-cloud",
    "kind": "STANDALONE",
    "galaxyId": null,
    "appCount": null,
    "diskTotalMb": null,
    "diskFreeMb": null,
    "diskState": null,
    "diskProbedAt": null,
    "name": "vibe-server-pd9l",
    "displayName": "vibe-server-pd9l",
    "description": null,
    "ip": "111.88.251.211",
    "ssh": {
      "user": "ubuntu",
      "port": 22,
      "hasPassword": true
    },
    "plan": "bc-small",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts",
    "monthlyCost": "24",
    "mode": "OPEN",
    "createdVia": "ui",
    "subdomain": "app-05b67cf7",
    "blackholeStatus": "CONNECTED",
    "accessPolicy": "OWNER_ONLY",
    "runtimeId": null,
    "runtimeStatus": null,
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.com",
    "localPort": 3000,
    "portPinned": true,
    "sleepAfterMinutes": null,
    "provisionError": null,
    "provisionErrorCode": null,
    "provisionReason": null,
    "b24CatalogSync": {
      "status": "IDLE",
      "itemId": null,
      "attempts": 0,
      "pendingOp": null,
      "eligible": true
    },
    "buildLog": null,
    "nextScheduledWakeAt": null,
    "wakeScheduleCapable": true,
    "buildHint": null,
    "createdAt": "2026-04-03T13:30:25.819Z"
  }
}

Host response by `galaxyId`

{
  "success": true,
  "data": {
    "id": "3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f",
    "status": "running",
    "kind": "GALAXY",
    "galaxyId": null,
    "name": "vibe-galaxy-host-q7x2",
    "displayName": "Shared Galaxy host",
    "createdAt": "2026-06-18T08:15:30.000Z",
    "access": {
      "via": "galaxy-reference",
      "allowedActions": ["read"],
      "allowedEndpoints": [
        "GET /v1/infra/servers",
        "GET /v1/infra/servers/:id"
      ],
      "_note": "This host is readable only because one of your galaxy applications references it. Host management and application operations must target resources owned by your key, not this shared host."
    }
  }
}

Error response example

404 — the server does not exist, is deleted, or the current key has no managing, team or reference access:

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

Errors

The full list of common API errors — Errors.

Known specifics

• A development-team member's card is shorter and does not poll the provider. With access.via: "collaborator" the fields ip, ssh, localPort, portPinned, deletedAt, appCount, the disk fields, wakeScheduleCapable and b24CatalogSync do not arrive, while monthlyCost, sleepAfterMinutes and nextScheduledWakeAt are added for the ADMIN role only. Application diagnostics stay in place: reachability, buildLog and buildHint arrive exactly as they do for the owner. The status on this branch comes from the platform's last measurement rather than being reconciled with the provider on the spot, so on a freshly created server it can lag by one polling tick — for a readiness-waiting loop use the key the server was created with.
• The galaxy-reference projection is shorter still and always uses stored state. It does not contact the provider or gateway even with status: "provisioning". The projection exists only while a live Galaxy application managed by the current key references a live GALAXY host in the same Bitrix24 account. It opens only this GET and the server list. /deploy, /exec, /upload, /logs, /sources, /ssh, /refresh, lifecycle, PATCH and DELETE remain unavailable for the host.
• For a full owner card, a provider request is made for provisioning or a missing IP. In either case, the server must have an external ID. When an IP is already stored, no request is made for running/stopped/sleeping/error. To force reconciliation, use POST /v1/infra/servers/:id/refresh.
• The readiness criterion is two fields. To continue working with the Deploy API you need both status: "running" and blackholeStatus: "CONNECTED" at the same time. If only running is set, the virtual machine is already up, but the tunnel agent has not connected yet. You do not have to wait forever: on a newly created standalone server (kind: "STANDALONE") that holds running with blackholeStatus: "NONE" for more than ten minutes the agent is not coming — the platform moves such a server to error with the code AGENT_NEVER_CONNECTED (see below). Runtime readiness after a deploy is determined by the success of the runtime step in the POST /:id/deploy response — the runtimeStatus field is not used for this, it is deprecated and stays null.
• blackholeStatus: "DISCONNECTED" with running — the tunnel lost its connection on a live server. Try POST /v1/infra/servers/:id/repair.
• AGENT_NEVER_CONNECTED — the agent never came up on a new machine. The virtual machine started normally, but the on-boot agent install did not finish, so there is no tunnel and there will not be one: the first-boot script runs once. The platform issues this verdict only for a newly created STANDALONE server (kind: "STANDALONE") that holds status: "running" with blackholeStatus: "NONE" for more than ten minutes — the server moves to error and billing for the machine is closed out. Try POST /v1/infra/servers/:id/repair first: it reinstalls the agent over SSH. If that does not help, recreate the server. POST /start on such a server answers 422 with the same code: starting it fixes nothing and erases the explanation. The verdict applies to Black Hole servers only — on an open-mode server running with blackholeStatus: "NONE" is a normal state. A galaxy host (kind: "GALAXY") does NOT get this code: the platform moves it to error too, but on its own threshold — fifteen minutes — and without a provisionErrorCode, so do not branch on the code for it; the reason arrives as text in provisionError. Should the agent connect on its own, the server returns to running and both provisionError and provisionErrorCode are cleared.
• monthlyCost pitfall: the field is returned as a string. Two such strings are compared character by character: "24" > "1000" returns true, and .sort() orders the values lexicographically, not numerically. Convert to a number via Number(data.monthlyCost).
• If you lost the SSH credentials from the creation response, they cannot be recovered. Recreate the SSH key manually via POST /v1/infra/servers/:id/exec (for BLACKHOLE) or recreate the server.
• GUEST_NOT_BOOTING is terminal — retrying does not help. The machine's guest operating system does not boot after an interrupted update. POST /repair and POST /start return 422 with the same code, availableActions keeps only delete, and billing for the machine has stopped. Applications hosted on such a machine are normally deleted one by one without a live tunnel — DELETE /v1/infra/servers/:id answers 200, after which the host itself can be deleted. The marker alone does not guarantee the 200: the platform also confirms through the gateway that no live tunnel exists, and that check is fail-safe — with the gateway unreachable the answer stays 502 (details on the DELETE page). A client that starts or repairs servers on a schedule must read this value: such a machine has to be recreated, not repaired.

See also

• Create a server
• List servers
• Update name and description
• Delete a server
• Refresh status
• Tunnel metrics