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

GET /v1/infra/servers

Возвращает серверы, которыми управляет текущий API-ключ, и серверы, где владелец ключа состоит в команде разработки. Каждая строка несёт блок 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 => {
  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,
        "hasPassword": true
      },
      "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,
      "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": "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 — Ошибки.

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

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

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

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