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

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.
• /wake не нужен при доступе через HTTPS-субдомен. Любое обращение к HTTPS-субдомену сервера само инициирует пробуждение BLACKHOLE-сервера. Явный /wake нужен, когда:
  • Клиенту нужен программный gate «сначала разбуди, потом делай» — через wait=true.
  • Сервер помечен preventWake=true (биллинговая блокировка, требует ручного действия).
• Проверка доступности ДО вызова. Перед /wake вызывайте `GET /v1/me` и смотрите capabilities.servers.wake.available. Если false, пользователю нужно совершить действие (пополнить баланс, обновить тариф) до того, как пробуждение станет возможным.
• Для error-сервера /wake не подходит — используйте `/start` или `/repair`.

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

• Запустить сервер — POST /v1/infra/servers/:id/start — ручной старт без блокировки.
• Усыпить сейчас — обратная операция.
• Восстановить туннель — если сервер проснулся, но туннель не подключается.
• Тариф и доступ — контекст для 402-ошибок.

#Запустить сервер

POST /v1/infra/servers/:id/start

Поднимает сервер из состояний sleeping, error или provisioning. Для sleeping виртуальная машина снова запускается у провайдера и возвращается к статусу running по мере готовности — вызов возвращает ответ сразу, не дожидаясь фактической готовности. Её нужно отслеживать опросом `GET /v1/infra/servers/:id`. Для error с подключённым туннелем (blackholeStatus: "CONNECTED") сервер сразу переводится в running без обращения к провайдеру. Для provisioning делается повторная попытка старта без сброса таймера ожидания. Для running сервера вызов возвращает 404.

#Параметры

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

#Примеры

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

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/start

#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/start

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

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/start`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
// Ждать готовности — опрашивать GET /v1/infra/servers/:id

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

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

#Поля ответа

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

{ "success": true }

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

404 — сервер в статусе running/deleted либо чужой:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Sleeping, error, or provisioning server not found"
  }
}

#Ошибки

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

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

• Блокирующий вариант. Если клиенту нужна полная готовность сервера перед следующим шагом — используйте `POST /wake?wait=true` вместо /start. Он ждёт status: "running" + blackholeStatus: "CONNECTED" до ~6.5 минут.
• Ручной /start обходит preventWake. В отличие от автоматического пробуждения при обращении к субдомену, явный POST /start снимает флаг preventWake и запускает сервер даже если он был заблокирован. Биллинговые блокировки (ACCOUNT_FROZEN) обходятся отдельным пополнением, не через /start.
• Для running возвращает 404, не 409. Сознательный выбор: сервер уже в нужном состоянии, делать нечего. Для перезагрузки — `POST /reboot`.

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

• Остановить сервер — POST /v1/infra/servers/:id/stop.
• Разбудить сервер (с `?wait=true`) — блокирующий вариант с ожиданием готовности.
• Немедленно усыпить — обратная операция.
• Обновить статус — принудительно опросить провайдера после старта.
• Получить сервер — опрос готовности.