Получить сервер

GET /v1/infra/servers/:id

Возвращает детали одного сервера по ID. Для полной владельческой карточки эндпоинт автоматически опрашивает облачного провайдера, когда сохранён статус provisioning или отсутствует IP, при условии, что у сервера есть внешний идентификатор. Удалённый сервер (status: "deleted") недоступен: возвращается 404.

Карточка бывает трёх форм. Управляющий ключ получает полный объект. Такую же форму без блока access получает ключ приложения для привязанного к нему сервера, кроме хоста GALAXY, даже если запись сервера закреплена за другим ключом приложения. Участник команды разработки получает 200 с укороченной карточкой. Если galaxyId живого galaxy-приложения текущего ключа указывает на живой общий хост того же портала, этот хост приходит как безопасная проекция для чтения с access.via: "galaxy-reference". Разбор форм и полей — Список серверов.

Параметры

Примеры

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

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

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

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

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

// Опрос готовности сервера
async function waitReady(serverId) {
  while (true) {
    const res = await fetch(
      `https://vibecode.bitrix24.tech/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('Для ожидания готовности используйте ID galaxy-приложения, а не хоста')
    }
    if (data.status === 'running' && data.blackholeStatus === 'CONNECTED') {
      return data
    }
    if (data.status === 'error') {
      throw new Error(`Сервер в ошибке: ${data.id}`)
    }
    await new Promise(r => setTimeout(r, 10000))
  }
}

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { data } = 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,
    "startCommand": null,
    "installCommand": null,
    "deployPort": null,
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.tech",
    "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"
  }
}

Пример хоста по `galaxyId`

{
  "success": true,
  "data": {
    "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."
    }
  }
}

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

404 — сервер не существует, удалён или у текущего ключа нет ни управляющего, ни командного, ни ссылочного доступа:

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

Ошибки

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

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

• Статус туннеля в карточке эффективный, но без побочных эффектов. Если работающий BLACKHOLE-сервер сохранён как CONNECTED, а его субдомена нет в успешном непустом снимке шлюза, ответ показывает DISCONNECTED. Недоступный или пустой снимок оставляет сохранённое значение. Запрос не запускает repair и не пишет результат сверки в базу. Это не относится к проекции galaxy-reference, которая всегда остаётся сохранённым снимком.
• Карточка участника команды разработки короче и не опрашивает провайдера. При access.via: "collaborator" не приходят ip, ssh, localPort, detectedPort, detectedPortObservedAt, portPinned, deletedAt, appCount, поля диска, wakeScheduleCapable и b24CatalogSync, а monthlyCost, sleepAfterMinutes и nextScheduledWakeAt добавляются только роли ADMIN. Диагностика приложения и параметры последнего деплоя при этом на месте: reachability, buildLog, buildHint, startCommand, installCommand и deployPort приходят так же, как владельцу. Статус в этой ветке берётся из последнего замера платформы, а не сверяется с провайдером на месте, поэтому у только что созданного сервера он может отставать на один такт опроса — для цикла ожидания готовности используйте ключ, которым сервер создавали.
• Проекция galaxy-reference ещё короче и всегда берётся из сохранённого состояния. Она не обращается к провайдеру или шлюзу даже при status: "provisioning". Проекция существует только пока живое galaxy-приложение текущего ключа ссылается на живой GALAXY-хост того же портала. Она открывает только этот GET и список серверов. /deploy, /exec, /upload, /logs, /sources, /ssh, /refresh, операции жизненного цикла, PATCH и DELETE для хоста не открываются.
• Для полной владельческой карточки запрос к провайдеру выполняется при provisioning или отсутствующем IP. В обоих случаях у сервера должен быть внешний идентификатор. Если IP уже сохранён, для running/stopped/sleeping/error запроса нет. Чтобы принудительно сверить состояние, используйте POST /v1/infra/servers/:id/refresh.
• Критерий готовности — два поля. Для продолжения работы с Deploy API нужны одновременно status: "running" и blackholeStatus: "CONNECTED". Если стоит только running — виртуальная машина уже жива, но агент туннеля ещё не подключился. Ждать бесконечно не нужно: у только что созданного отдельного сервера (kind: "STANDALONE"), который держит running при blackholeStatus: "NONE" дольше десяти минут, агент уже не поднимется — платформа переводит такой сервер в error с кодом AGENT_NEVER_CONNECTED (см. ниже). Готовность рантайма после деплоя определяется успехом шага runtime в ответе POST /:id/deploy — поле runtimeStatus для этого не используется, оно устаревшее и остаётся null.
• blackholeStatus: "DISCONNECTED" при running — туннель потерял связь у живого сервера. Попробуйте POST /v1/infra/servers/:id/repair.
• AGENT_NEVER_CONNECTED — на новой машине не поднялся агент. Виртуальная машина запустилась штатно, но установка агента при старте не завершилась, поэтому туннеля нет и не будет: скрипт первой загрузки выполняется один раз. Отдельному серверу (kind: "STANDALONE") платформа выносит этот вердикт, только пока он только что создан и держит status: "running" при blackholeStatus: "NONE" дольше десяти минут: сервер переводится в error, начисление за машину закрывается. Сначала попробуйте POST /v1/infra/servers/:id/repair — он ставит агента заново по SSH; если не помогло, пересоздайте сервер. POST /start на таком сервере отвечает 422 с этим же кодом: запуск ничего не чинит, а объяснение стирает. Вердикт выносится только серверам в режиме Black Hole — для сервера в открытом режиме running при blackholeStatus: "NONE" это нормальное состояние. Хост-галактика (kind: "GALAXY") получает тот же код по своему порогу — пятнадцать минут в running при blackholeStatus: "NONE" — и не только после создания: вердикт выносится всякий раз, когда хост снова дольше порога остаётся в этом состоянии. Уже существующие хосты-галактики, у которых до этого изменения сохранился старый текст provisionError, сохраняют provisionErrorCode: null в ответах GET, но /start и availableActions распознают это точное legacy-описание и предлагают только восстановление. Остальное совпадает: начисление закрывается, POST /start отвечает 422 с этим кодом, лечится ремонтом. Если агент подключится сам, сервер вернётся в running, а provisionError и provisionErrorCode очистятся.
• DISK_FULL — ремонт не смог поставить агента: на диске сервера нет места. Код записывает ремонт, завершившийся неудачей. Повтор ремонта поможет только после того, как на диске освободится место. Успешный ремонт снимает код. Сервер при этом не переходит в error. Если ремонт будил спящий сервер, после неудачи машина остаётся запущенной до авто-сна, а при выключенном авто-сне — пока её не остановят.
• Подводный камень monthlyCost: поле возвращается строкой. Сравнение двух таких строк идёт посимвольно: "24" > "1000" вернёт true, а .sort() выстроит значения не по величине. Приводите к числу через Number(data.monthlyCost).
• Если потеряли SSH-креды из ответа создания — восстановить нельзя. Пересоздайте SSH-ключ вручную через POST /v1/infra/servers/:id/exec (для BLACKHOLE) или пересоздайте сервер.
• GUEST_NOT_BOOTING — терминальное состояние, повтор не поможет. Гостевая операционная система машины не загружается. POST /repair и POST /start отвечают 422 с этим кодом, в availableActions остаётся только delete, начисление за машину закрыто. Удаление приложения требует подтверждённого удаления контейнера: DELETE /v1/infra/servers/:id возвращает 502 GALAXY_HOST_UNREACHABLE, если teardown не подтверждён, сохраняя приложение и его привязку. Восстановите доступ к хосту и повторите запрос либо обратитесь в поддержку платформы для подтверждения уничтожения облачной машины и завершения уборки. Клиент по расписанию должен пересоздать такую машину вместо повторных запусков и ремонта.

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

• Создать сервер
• Список серверов
• Обновить имя и описание
• Удалить сервер
• Обновить статус
• Метрики туннеля