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

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": "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": "Не повторяйте автоматически — нужно действие пользователя"
  }
}

Ошибки

Полный список общих ошибок 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: обычный запрос получает страницу входа со статусом 200, а API-клиент — запрос с заголовком Accept: application/json, Authorization: Bearer или X-Requested-With: XMLHttpRequest, а также любой запрос по пути /api/ — получает 401 BH_LOGIN_REQUIRED. На сервере с политикой 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, пользователю нужно совершить действие (пополнить баланс, обновить тариф) до того, как пробуждение станет возможным.
• Публичный адрес машины после пробуждения другой. Проснувшаяся машина получает адрес заново, поэтому поле 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-приложение.

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

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