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

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

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

#Параметры

Параметр В Тип Обяз. По умолч. Описание
id path string (UUID) да — ID сервера в статусе sleeping или provisioning
wait query string нет — true — блокирующий режим: ответ вернётся только когда сервер готов (до 4.5 минут) или сработает таймаут. Любое другое значение — асинхронный режим, ответ сразу

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

#Примеры

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

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

# Блокирующий — ждёт готовности до ~4.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-приложение

Terminal 
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 — личный ключ

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: showпользователю 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-приложение

javascript 
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',
    },
  }
)

#Поля ответа

Поле Тип Описание
success boolean true при успешном пробуждении
data.id string (UUID) ID сервера
data.status string Актуальный статус (RUNNING при wait=true успехе; PROVISIONING в асинхронном режиме)
data.blackholeStatus string Состояние туннеля (CONNECTED в блокирующем при успехе)
data.appUrl string | null HTTPS-адрес приложения

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

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

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

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Waking this server requires a commercial Bitrix24 plan or an active trial",
    "userMessage": "Для пробуждения сервера нужен коммерческий тариф Битрикс24 или активный trial. Оформите тариф на https://www.bitrix24.ru/prices/",
    "alternatives": [
      "Обновить тариф Битрикс24 и повторить",
      "Перейти на AI Router с BYOK-ключами — он работает на любом тарифе"
    ],
    "hint": "Не повторяйте автоматически — нужно действие пользователя"
  }
}

#Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
402 COMMERCIAL_PLAN_REQUIRED Бесплатный тариф и trial недоступен — обновите тариф Битрикс24
402 TRIAL_EXPIRED Trial использован и завершился
402 BILLING_EXHAUSTED Баланс Вайбкод исчерпан — пополните
402 ACCOUNT_FROZEN Баланс заморожен
403 SERVER_WAKE_BLOCKED Пробуждение заблокировано не из-за биллинга (завершённый trial, административный блок, нарушения безопасности)
404 NOT_FOUND Сервер не в статусе sleeping/provisioning, удалён или принадлежит другому API-ключу
422 VM_MISSING У записи нет externalId — виртуальная машина не создана у провайдера. Удалите сервер и создайте новый
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы
502 PROVIDER_ERROR Облачный провайдер вернул ошибку при запуске виртуальной машины
504 WAKE_TIMEOUT Блокирующий ?wait=true не дождался готовности (таймаут ~4.5 минуты). Сервер возвращается в sleeping — попробуйте снова

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

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

  • Поведение при таймауте ?wait=true. Если за ~4.5 минуты виртуальная машина не поднялась, эндпоинт возвращает 504 WAKE_TIMEOUT и пробует откатить сервер в sleeping — чтобы квота не висела на «вечно зависшем» сервере. Поможет повторный /wake или `/repair`.
  • Rich-error поля для AI-агентов. При 402/403 тело ошибки дополнительно содержит userMessage (переведённая формулировка для пользователя), alternatives (список путей решения) и hint (совет AI-агенту, повторять автоматически или нет). Используйте эти поля в UI вместо голого code/message.
  • /wake редко нужен явно. Любое обращение к HTTPS-субдомену сервера само инициирует пробуждение BLACKHOLE-сервера. Явный /wake нужен, когда:
    • Клиенту нужен программный gate «сначала разбуди, потом делай» — через wait=true.
    • Сервер помечен preventWake=true (биллинговая блокировка, требует ручного действия).
  • Проверка доступности ДО вызова. Перед /wake вызывайте `GET /v1/me` и смотрите capabilities.servers.wake.available. Если false, пользователю нужно совершить действие (пополнить баланс, обновить тариф) до того, как пробуждение станет возможным.
  • Для error-сервера /wake не подходит — используйте `/start` или `/repair`.

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