List servers

GET /v1/infra/servers

Returns three groups: servers managed by the current API key, galaxy hosts referenced by its Galaxy applications, and servers whose development team the key owner is on. A referenced host arrives only as a safe read-only row with access.via: "galaxy-reference". Every row carries an access block explaining why it is visible. Deleted servers managed by the key (status: "deleted") are not included by default — pass ?includeDeleted=true to see them. The parameter does not return deleted hosts or references through deleted applications. Other servers are not visible, even within the same Bitrix24 account. To view every server in the account, use the administrator panel in the Vibecode dashboard.

Query parameters

Why this exists: sources outlive their server. Once you delete a server, you can still list, untag, download or clean up its source versions — but for that you need its ID, and there is nowhere else to get it. The sources contract lives on the Source storage page.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data: servers } = await res.json()

servers.forEach(s => {
  if (s.access.via === 'galaxy-reference') {
    console.log(`${s.name}: shared host is read-only`)
    return
  }
  const ready = s.status === 'running' && s.blackholeStatus === 'CONNECTED'
  console.log(`${s.name}: ${ready ? '✓ ready' : s.status} — ${s.appUrl}`)
})

JavaScript — OAuth application

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

Response fields

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
      },
      "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",
      "sleepAfterMinutes": null,
      "provisionError": null,
      "provisionErrorCode": null,
      "provisionReason": null,
      "b24CatalogSync": {
        "status": "IDLE",
        "itemId": null,
        "attempts": 0,
        "pendingOp": null,
        "eligible": true
      },
      "createdAt": "2026-04-03T13:30:25.819Z",
      "access": { "via": "owner" }
    },
    {
      "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."
      }
    },
    {
      "id": "b0f4c8a2-7d31-4e56-9a10-2c6f5b83de47",
      "status": "running",
      "provider": "bitrix-cloud",
      "kind": "GALAXY_APP",
      "galaxyId": "3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f",
      "name": "vibe-app-mk4t",
      "displayName": "Request tracker",
      "description": null,
      "plan": "bc-small",
      "region": "eu-central-1a",
      "image": "ubuntu-2404-lts",
      "mode": "BLACKHOLE",
      "createdVia": "galaxy",
      "subdomain": "app-91c40e7b",
      "blackholeStatus": "CONNECTED",
      "accessPolicy": "PORTAL",
      "runtimeId": null,
      "runtimeStatus": null,
      "appUrl": "https://app-91c40e7b.vibecode.bitrix24.com",
      "provisionError": null,
      "provisionErrorCode": null,
      "provisionReason": null,
      "createdAt": "2026-08-14T09:12:47.301Z",
      "access": {
        "via": "collaborator",
        "role": "DEVELOPER",
        "allowedActions": ["read", "code", "sources", "wake"],
        "allowedEndpoints": [
          "GET /v1/infra/servers/:id",
          "POST /v1/infra/servers/:id/deploy",
          "POST /v1/infra/servers/:id/exec",
          "POST /v1/infra/servers/:id/upload",
          "GET /v1/infra/servers/:id/logs",
          "GET /v1/infra/servers/:id/sources",
          "GET /v1/infra/servers/:id/sources/:versionId/download",
          "POST /v1/infra/servers/:id/sources",
          "POST /v1/infra/servers/:id/wake"
        ],
        "_note": "You are on this server's development team, not its owner. Deploying and changing the application code is fully available to you through `allowedEndpoints` — no extra grant and no API-key rebind is needed. Server management (lifecycle, tariff, SSH, access lists) answers 403 SERVER_ROLE_FORBIDDEN and names your role; that is the expected boundary, not a broken permission."
      }
    }
  ]
}

Error response example

401 — no API key passed:

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• An empty array while servers are running means the current key does not manage them, you are not on their development teams, and its live Galaxy applications do not reference their live hosts. After the previous key expires or is revoked, the server stays bound to it. If the previous key is deleted, the server is left without a managing key. In both cases a new key returns an empty data while the servers keep running and remain visible in the dashboard. How to restore access — Server access recovery.
• Even a Bitrix24 account administrator sees only their own servers, hosts referenced by their own Galaxy applications, and servers whose development team they are on. For an account-wide picture, use the administrator panel in the dashboard — this output does not take account-administrator rights into account.
• A team member's row is shorter than the owner's. It is assembled from its own set of fields rather than by cutting private ones out of the owner's: with access.via: "collaborator" the fields ip, ssh, deletedAt, appCount, the disk fields, wakeScheduleCapable and b24CatalogSync do not arrive. Costs (monthlyCost) and the sleep threshold with the next wake-up (sleepAfterMinutes, nextScheduledWakeAt) are added for the ADMIN role only. So check whether a field is present on the row rather than treating it as mandatory.
• A management operation outside your role answers 403 SERVER_ROLE_FORBIDDEN, not 404. The refusal names your role, the required threshold and the calls open to you in error.hint. This is the boundary of the role, not lost access: an API-key rebind and a fresh grant are both beside the point — work through the list in access.allowedEndpoints, or ask the owner to run the operation. For a key unrelated to the server, the server's existence is still not disclosed — 404 stays there.
• A galaxy-reference host is read-only. The row appears while a live Galaxy application managed by the current key references a live GALAXY host in the same Bitrix24 account. Multiple applications on one host produce one row. If the key also manages the host, the full owner row arrives. A reference row has no role, provider, network, SSH, plan, billing, capacity, build or runtime data. Every host call except the two GET operations in allowedEndpoints keeps answering as it would for an unrelated key.
• Only live servers of your own Bitrix24 account arrive through membership. Galaxy hosts (kind: "GALAXY") are not shown to a team member. They appear only through the separate galaxy-reference standing. Deleted servers never arrive through membership even with ?includeDeleted=true — that parameter applies only to servers managed by the current key. A server the key manages and whose team you are also on arrives as one row with access.via: "owner".
• appUrl on a member's row is empty until the application's audience opens it to you. The field is filled only if the server's access policy (accessPolicy) opens the application to everyone in the Bitrix24 account, or you hold a personal grant. Team membership gives you the code, not the right to open the application. There is one exception: if your access comes through a department, you can open the application, but the field will not show the link — the owner or a team administrator names it for you.
• Servers of Bitrix24 accounts marked as deleted are hidden automatically. The platform checks account availability daily: if an account responds with 410/403 three days in a row, it is marked as deleted and its servers stop being displayed.
• Without page/limit the response is not paginated. Managed servers and unique referenced hosts always arrive in full. page/limit slice only the servers whose development team you are a member of. With pagination, total counts all three groups without duplicates.
• includeDeleted=true does not surface servers of deleted Bitrix24 accounts or restore reference access. Account-level hiding applies regardless of the parameter value. A deleted application or host also produces no galaxy-reference row.
• 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. 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
• Get a server
• Update name and description
• Delete a server
• Lifecycle
• Server access recovery