Разбудить сервер

POST /v1/infra/servers/:id/wake

Пробуждает сервер из sleeping или provisioning. В отличие от /start, /wake поддерживает блокирующий режим через ?wait=true — ответ возвращается только когда сервер полностью готов (виртуальная машина запущена и туннель подключился) или сработал таймаут. Пока платформа ждёт, она сама переспрашивает облако о состоянии машины и повторяет команду запуска, если та не доехала. Подключённый туннель считается доказательством готовности, даже если статус сервера ещё не успел обновиться. Используйте блокирующий режим, когда клиенту нужна готовность перед следующим шагом (cron-задача, триггерный вызов), и асинхронный — когда можно подождать на опросе.

Параметры

Тело запроса пустое.

Примеры

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

# Асинхронный вызов — ответ сразу, готовность проверяйте опросом
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake

# Блокирующий — ждёт готовности до ~6.5 минут
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake?wait=true"

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

curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake?wait=true"

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

// Блокирующий вариант — проще всего для последующих шагов
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/wake?wait=true`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (!body.success) {
  // Rich-error: показать пользователю userMessage, предложить alternatives
  console.error(body.error.userMessage ?? body.error.message)
  if (body.error.alternatives) console.log('Варианты:', body.error.alternatives)
  throw new Error(body.error.code)
}
console.log(`Сервер готов: ${body.data.appUrl}`)

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/wake?wait=true`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Поля ответа

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

Успешное пробуждение (?wait=true):

{
  "success": true,
  "data": {
    "id": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "status": "running",
    "blackholeStatus": "CONNECTED",
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.tech"
  }
}

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

402 — баланс заморожен, сервер не поднимется до пополнения (расширенный формат ошибки для AI-агентов):

{
  "success": false,
  "error": {
    "code": "BILLING_EXHAUSTED",
    "message": "Balance depleted — top up to resume",
    "userMessage": "Баланс Вайбкод исчерпан. Пополните счёт, чтобы возобновить работу серверов.",
    "alternatives": [
      { "type": "topup", "description": "Пополнить баланс в разделе биллинга" }
    ],
    "hint": "Ask the user to top up their VibeCode balance. After top-up the server can be woken normally."
  }
}

Ошибки

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

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

• Поведение при таймауте ?wait=true. Если за ~6.5 минуты виртуальная машина не поднялась, эндпоинт возвращает 503 WAKE_TIMEOUT и пробует откатить сервер в sleeping — чтобы квота не висела на «вечно зависшем» сервере. Внутри этого окна платформа повторяет команду запуска, если облако её потеряло, поэтому таймаут означает, что машина действительно не поднялась, а не что команда не дошла. Поможет повторный /wake или /repair.
• Поля расширенной ошибки для AI-агентов. При 402/403 тело ошибки дополнительно содержит userMessage (переведённая формулировка для пользователя), alternatives (список путей решения) и hint (совет AI-агенту, повторять автоматически или нет). Используйте эти поля в UI вместо голого code/message.
• Пробуждение по обращению к субдомену срабатывает не на каждый запрос. Оно запускается в четырёх случаях: у сервера политика доступа PUBLIC, посетитель авторизован, запрос пришёл с токеном доступа режима api-bearer, получатель открыл ссылку режима share-url. Сервер с запретом на пробуждение не поднимется и в этих случаях — см. пункт ниже. Запрос без авторизации к серверу с любой другой политикой, включая OWNER_ONLY по умолчанию, оставляет сервер в статусе sleeping и получает отказ аутентификации. Оба представления используют HTTP 401: браузерная навигация получает HTML-страницу входа, а машинный запрос — JSON BH_LOGIN_REQUIRED. JSON выбирается по Accept: application/json, Content-Type: application/json, Authorization: Bearer, X-Api-Key, X-Requested-With: XMLHttpRequest, пути /v1/… или /api/… либо любому ненавигационному значению Sec-Fetch-Dest (включая empty); запрос без явного HTML и без назначения тоже по умолчанию получает JSON. Эти признаки имеют приоритет над явным HTML и Sec-Fetch-Dest: document|iframe|frame. Поэтому голый POST с Accept: */* получает JSON 401. На сервере с политикой PUBLIC запросы GET и HEAD от поисковых роботов и автоматических клиентов — например curl, wget, python-requests, go-http-client, java/, браузеры без интерфейса и запрос без заголовка User-Agent — машину не поднимают, чтобы обход роботом не держал её включённой. На таком сервере запросы POST, PUT, PATCH и DELETE будят её от любого клиента: это вызовы вебхуков и API, а не обход. Из скрипта и из консоли поднимайте сервер явным /wake с wait=true — тогда ответ придёт, когда сервер уже принимает запросы.
• Сервер с флагом preventWake вызов /wake не поднимает — коды отказа в таблице выше. Запрет ставится при заморозке баланса, окончании доступа к платформе и административной блокировке, а сервер агента или бота получает его при любой остановке — из карточки или вызовом /sleep-now. Отдельный сервер поднимает /start: он снимает запрет, но заморозку баланса не обходит. У galaxy-приложения запрет на хосте блокирует и /start — см. Galaxy-приложение.
• Проверка доступности ДО вызова. Перед /wake вызывайте GET /v1/me и смотрите capabilities.servers.wake.available. Если false, пробуждение сейчас недоступно: заморожен баланс или ограничен ключ — причину называет поле reason. Этот признак не учитывает ни тариф, ни запрет на пробуждение самого сервера, поэтому и при true возможен 403 SERVER_WAKE_BLOCKED.
• Публичный адрес машины после пробуждения другой. Проснувшаяся машина получает адрес заново, поэтому поле ip в GET /v1/infra/servers/:id после каждого цикла сна отдаёт новое значение. Это относится ко всем тарифам, включая невытесняемые. То, что обращается к серверу по адресу — запись DNS, внешний мониторинг, — переводите на HTTPS-субдомен из поля appUrl: пробуждение его не меняет. Обратное направление так не лечится: когда внешний сервис пускает только по списку разрешённых IP, подставить в этот список нечего — постоянного исходящего адреса платформа не даёт ни в одной модели размещения, подробности в разделе Исходящий IP.
• Для error-сервера /wake не подходит — используйте /start или /repair.

Galaxy-приложения (`kind=GALAXY_APP`)

Параметр ?wait=true на galaxy-приложении ожидания готовности не даёт: ответ приходит сразу, кода WAKE_TIMEOUT здесь не бывает. После холодного старта хоста приложение какое-то время остаётся в статусе sleeping — отслеживайте готовность опросом GET /v1/infra/servers/:id.

Полная карта операций жизненного цикла приложения — Galaxy-приложение.

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

• Запустить сервер
• Усыпить сейчас
• Восстановить туннель
• Тариф и доступ