Список серверов

GET /v1/infra/servers

Возвращает три группы: серверы текущего API-ключа, хосты-галактики, на которые ссылаются его galaxy-приложения, и серверы, где владелец ключа состоит в команде разработки. У хоста по ссылке приходит только безопасная строка для чтения с access.via: "galaxy-reference". Каждая строка несёт блок access, который объясняет основание доступа. Удалённые серверы текущего ключа (status: "deleted") по умолчанию не попадают в выдачу — чтобы их увидеть, передайте ?includeDeleted=true. Параметр не возвращает удалённые хосты или ссылки через удалённые приложения. Остальные серверы не видны даже в том же портале. Для просмотра всех серверов портала используйте панель администратора в личном кабинете.

Параметры запроса

Зачем это нужно: исходники переживают сервер. Удалив сервер, вы по-прежнему можете посмотреть его версии исходников, снять с них тег, скачать или очистить — но для этого нужен его идентификатор, а получить его больше неоткуда. Контракт исходников описан на странице Хранилище исходников.

Примеры

curl — личный ключ

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

curl — OAuth-приложение

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

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/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}: общий хост доступен только для чтения`)
    return
  }
  const ready = s.status === 'running' && s.blackholeStatus === 'CONNECTED'
  console.log(`${s.name}: ${ready ? '✓ готов' : s.status} — ${s.appUrl}`)
})

JavaScript — OAuth-приложение

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

Поля ответа

Пример ответа

{
  "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": "ru-central1-a",
      "image": "fd80bm0rh4rkepi5ksdi",
      "monthlyCost": "1200",
      "mode": "OPEN",
      "createdVia": "ui",
      "subdomain": "app-05b67cf7",
      "blackholeStatus": "CONNECTED",
      "accessPolicy": "OWNER_ONLY",
      "runtimeId": null,
      "runtimeStatus": null,
      "appUrl": "https://app-05b67cf7.vibecode.bitrix24.tech",
      "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
      },
      "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": "Общий хост Galaxy",
      "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": "Учёт заявок",
      "description": null,
      "plan": "bc-small",
      "region": "ru-central1-a",
      "image": "fd80bm0rh4rkepi5ksdi",
      "mode": "BLACKHOLE",
      "createdVia": "galaxy",
      "subdomain": "app-91c40e7b",
      "blackholeStatus": "CONNECTED",
      "accessPolicy": "PORTAL",
      "runtimeId": null,
      "runtimeStatus": null,
      "appUrl": "https://app-91c40e7b.vibecode.bitrix24.tech",
      "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."
      }
    }
  ]
}

Пример ответа при ошибке

401 — не передан API-ключ:

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

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

• Сверка туннелей выполняется одним снимком и ничего не чинит. Для работающих BLACKHOLE-серверов со статусом CONNECTED список использует один текущий снимок шлюза. В непустом снимке отсутствующий субдомен показывается как DISCONNECTED; недоступный шлюз или успешный пустой connections[] считаются неоднозначными для всего флота и сохраняют значения из базы. GET не пишет статусы и не запускает repair; строки galaxy-reference в сверку не входят.
• Пустой массив при работающих серверах означает, что текущий ключ ими не управляет, вы не состоите в их командах разработки и его живые galaxy-приложения не ссылаются на их живые хосты. После истечения или отзыва прежнего ключа сервер остаётся привязан к нему. Если прежний ключ удалён, сервер остаётся без управляющего ключа. В обоих случаях новый ключ возвращает пустой data, хотя серверы работают и видны в личном кабинете. Как вернуть доступ — Восстановление доступа к серверу.
• Даже администратор портала видит только свои серверы, хосты по ссылкам собственных galaxy-приложений и серверы, где он в команде разработки. Для портальной картины используйте панель администратора в личном кабинете — прав администратора портала эта выдача не учитывает.
• Строка участника команды короче владельческой. Она собирается отдельным набором полей, а не вырезанием приватных из владельческого: при access.via: "collaborator" не приходят ip, ssh, deletedAt, appCount, поля диска, wakeScheduleCapable и b24CatalogSync. Расходы (monthlyCost) и порог сна с ближайшим пробуждением (sleepAfterMinutes, nextScheduledWakeAt) добавляются только роли ADMIN. Поэтому проверяйте наличие поля в строке, а не считайте его обязательным.
• Управляющая операция вне вашей роли отвечает 403 SERVER_ROLE_FORBIDDEN, а не 404. Отказ называет вашу роль, требуемый порог и открытые вам вызовы в error.hint. Это граница роли, а не потерянный доступ: перепривязка ключа и выдача прав заново тут ни при чём — работайте по списку access.allowedEndpoints либо попросите владельца выполнить операцию. Ключу, который серверу посторонний, существование сервера по-прежнему не раскрывается — там остаётся 404.
• Хост galaxy-reference доступен только для чтения. Строка появляется, пока живое galaxy-приложение текущего ключа ссылается на живой GALAXY-хост того же портала. Несколько приложений на одном хосте дают одну строку. Если ключ управляет и хостом, приходит полная строка owner. У строки по ссылке нет role, данных провайдера, сети, SSH, тарифа, биллинга, ёмкости, сборки или рантайма. Все вызовы к хосту, кроме двух GET из allowedEndpoints, продолжают отвечать так же, как постороннему ключу.
• По членству приходят только живые серверы своего портала. Машины-галактики (kind: "GALAXY") участнику команды не показываются. Они появляются только по отдельному основанию galaxy-reference. Удалённые серверы не приходят по членству даже с ?includeDeleted=true — этот параметр действует только на серверы текущего ключа. Сервер, которым ключ управляет и в команде которого вы состоите, приходит одной строкой с access.via: "owner".
• appUrl у строки участника пуст, пока аудитория приложения не открывает его вам. Поле заполняется, только если политика доступа сервера (accessPolicy) открывает приложение всем сотрудникам портала либо вам выдан личный грант. Членство в команде даёт код, а не право открыть приложение. Исключение — доступ через подразделение: открыть приложение вы можете, а ссылку поле не покажет, её называет владелец или администратор команды.
• Серверы порталов, помеченных удалёнными в Битрикс24, автоматически скрываются. Платформа ежедневно проверяет доступность порталов: если портал отвечает 410/403 три дня подряд, он помечается как удалённый и его серверы перестают отображаться.
• Без page/limit ответ не пагинируется. Собственные серверы и уникальные хосты по ссылке всегда приходят целиком. page/limit режут только серверы, где вы участник команды разработки. При пагинации total считает все три группы без дублей.
• includeDeleted=true не показывает серверы удалённых порталов и не восстанавливает ссылочный доступ. Скрытие удалённого портала действует при любом значении параметра. Удалённое приложение или хост тоже не создают строку galaxy-reference.
• GUEST_NOT_BOOTING — терминальное состояние, повтор не поможет. Гостевая операционная система машины не загружается после прерванного обновления. POST /repair и POST /start отвечают 422 с этим же кодом, в availableActions остаётся только delete, начисление за машину закрыто. Клиент, который запускает или ремонтирует серверы по расписанию, обязан читать это значение: такую машину нужно пересоздать, а не чинить.
• DISK_FULL — ремонт не смог поставить агента: на диске сервера нет места. Повтор ремонта поможет только после того, как на диске освободится место. Успешный ремонт снимает код. Разбор — Получить сервер.

Смотрите также

• Создать сервер
• Получить сервер
• Обновить имя и описание
• Удалить сервер
• Жизненный цикл
• Восстановление доступа к серверу