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 the IP is absent, provided the server has an external ID. A deleted server (status: "deleted") is not accessible: a 404 is returned.

The card comes in three shapes. The managing key gets the full object. An application key gets the same shape, without the access block, for the server bound to it — except for a GALAXY host — even when the server record 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,
    "startCommand": null,
    "installCommand": null,
    "deployPort": null,
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.com",
    "localPort": 3000,
    "detectedPort": 3000,
    "detectedPortObservedAt": "2026-09-15T08:15:30.000Z",
    "portPinned": false,
    "sleepAfterMinutes": null,
    "idleSleepProtected": false,
    "runMode": "IDLE",
    "workSchedule": 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

• The card uses an effective tunnel status without side effects. If a running BLACKHOLE server is stored as CONNECTED but its subdomain is absent from a successful non-empty gateway snapshot, the response shows DISCONNECTED. An unavailable or empty snapshot preserves the stored value. The request does not run repair or write the check result to the database. This does not apply to the galaxy-reference projection, which always remains a stored snapshot.
• A development-team member's card is shorter and does not poll the provider. With access.via: "collaborator" the fields ip, ssh, localPort, detectedPort, detectedPortObservedAt, 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 and the last deploy parameters stay in place: reachability, buildLog, buildHint, startCommand, installCommand and deployPort arrive exactly as they do for the owner. In this card, the status 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 grants access only to this GET and the server list. /deploy, /exec, /upload, /logs, /sources, /ssh, /refresh, lifecycle operations, PATCH and DELETE remain unavailable for the host.
• For a full owner card, a provider request is made when the status is provisioning or the IP is missing. 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 will not come up — 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. For a standalone server (kind: "STANDALONE") the platform issues this verdict only while it is newly created and 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") gets the same code on its own threshold — fifteen minutes in running with blackholeStatus: "NONE" — and not only right after creation: the verdict is issued whenever the host stays in that state past the threshold again. Existing galaxy hosts that already had the legacy provisionError text before this change keep provisionErrorCode: null in GET responses, but /start and availableActions recognize that exact legacy reason and expose the same repair-only behavior. The rest is the same: billing is closed out, POST /start answers 422 with this code, and repair fixes it. Should the agent connect on its own, the server returns to running and both provisionError and provisionErrorCode are cleared.
• DISK_FULL — the repair could not install the agent: the server's disk is full. The code is recorded by a repair that failed. Repeating the repair helps only once disk space has been freed. A successful repair clears the code. The server does not move to error. If the repair woke a sleeping server, the machine stays running after the failure until auto-sleep, or until someone stops it if auto-sleep is off.
• 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 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