Настроить авто-сон

PATCH /v1/infra/servers/:id/sleep

Настраивает сохранённый таймер автоматического засыпания BLACKHOLE-сервера. При отсутствии входящих HTTP-запросов к приложению в течение фактического таймаута сервер автоматически останавливается. Поднять его снова можно вызовом /wake, а обращение к HTTPS-субдомену будит сервер не в каждом случае — условия там же. Передача null сохраняет настройку «Никогда», но действующее расписание пробуждения меняет фактический таймаут между окнами — подробности ниже.

Без действующего расписания null отключает наш авто-сон по бездействию. Если у сервера есть следующее пробуждение по включённому и доступному расписанию, вместо «Никогда» применяется платформенный таймаут после окна — по умолчанию 15 минут простоя. Явно заданное число (15, 30, 60 или 240) всегда имеет приоритет над этим значением.

Сервер с idleSleepProtected: true должен оставаться на связи, поэтому запрос с числовым порогом отвечает 400 AGENT_IDLE_SLEEP_FORBIDDEN. Это сервер агента или бота либо обычное приложение с активным fetch-ботом. null и режим работы по расписанию остаются доступны.

Если сервер стоит на вытесняемом (preemptible) тарифе (bc-agent, bc-micro — см. Тарифы), облако также может принудительно перезапускать такую машину примерно раз в сутки, с коротким окном недоступности. Платформа автоматически будит её обратно. Для непрерывной 24/7-нагрузки нужны невытесняемый тариф (bc-small и выше), настройка null и отсутствие действующего расписания пробуждения.

Параметры

Поля запроса (body)

Примеры

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

# Включить авто-сон через 60 минут простоя
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'

# Отключить авто-сон
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": null}'

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

curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: 60 }),
  }
)
const { data } = await res.json()
console.log(`Авто-сон через ${data.sleepAfterMinutes} мин`)

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

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: null }),
  }
)

Поля ответа

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

{
  "success": true,
  "data": {
    "sleepAfterMinutes": 60,
    "workScheduleCleared": false
  }
}

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

400 — некорректное значение sleepAfterMinutes:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sleepAfterMinutes must be 15, 30, 60, 240, or null"
  }
}

400 — сервер не в BLACKHOLE:

{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Sleep settings are only available for BLACKHOLE servers"
  }
}

400 — попытка включить гарантированный режим «Всегда онлайн» (null на невытесняемом тарифе) при включённых окнах пробуждения, если сервер не в режиме работы SCHEDULE:

{
  "success": false,
  "error": {
    "code": "ALWAYS_ON_CONFLICT",
    "message": "The server has enabled wake-schedule windows, which conflict with always-on (24/7) mode. Delete or disable the wake windows first, or keep a sleep timeout."
  }
}

Ошибки

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

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

• Что считается активностью и сбрасывает таймер. Таймер сбрасывают входящие HTTP-запросы к приложению через туннель. Реальная активность проверяется раз в несколько минут через Gateway-метрики, момент последнего обращения виден полем lastRequestAt в GET /v1/infra/servers/:id/metrics. Запросы, которые приложение отправляет само наружу, активностью не считаются. Отдельно платформа защищает приложение с активным fetch-ботом: у него idleSleepProtected: true, числовой порог недоступен и исходящий опрос не обязан имитировать входящий трафик. Для остальных приложений исходящий опрос собственную машину в сети не удерживает. Значение null отключает такой сон только без действующего расписания пробуждения.
• Авто-пробуждение сохраняется. Сервер, заснувший по таймеру, просыпается при вызове /deploy//wake//start, а обращение к HTTPS-субдомену будит его на условиях автоматического пробуждения.
• Значение по умолчанию для новых серверов — 60 минут. Текущее значение — в поле GET /v1/infra/servers/:id.
• Серверы агентов, управляемых ботов и приложения с активным fetch-ботом без расписания не засыпают по простою. У машин, которые платформа создаёт сама под AI-агента или управляемого бота, поле createdVia равно agent или bot. Обычный сервер или galaxy-приложение получает ту же защиту, пока с ним связан включённый fetch-бот. Во всех случаях GET /v1/infra/servers/:id возвращает idleSleepProtected: true, а запрос с числовым sleepAfterMinutes отклоняется с 400 AGENT_IDLE_SLEEP_FORBIDDEN. Сохранённый прежний порог у обычного приложения не стирается и снова начнёт действовать после отключения последнего fetch-бота. Расписание остаётся доступным и сильнее защиты. Webhook-бот сам по себе защиту не включает.
• ALWAYS_ON_CONFLICT защищает только режим «Всегда онлайн». На вытесняемом тарифе null совместим с расписанием: при действующем окне включается платформенный таймаут после окна. На невытесняемом тарифе правила асимметричны: запрос sleepAfterMinutes: null отклоняется, пока есть включённое окно пробуждения, а создание или обновление любого окна отклоняется, пока сохранён null, даже если в запросе передано enabled: false. Исключений два: приложение в галактике — тариф оно не выбирает, а наследует от галактики, — и сервер в режиме работы SCHEDULE: сон у него объявлен расписанием. Отказ за сохранённый null не получает ни один из них. Удаление окна разрешено. Для уже существующей комбинации null с действующим расписанием применяется платформенный таймаут после окна. Перед переходом в «Никогда» удалите или отключите включённые окна либо оставьте числовой таймаут.
• Запись таймаута снимает назначенное расписание работы. Расписание сильнее таймаута: пока оно назначено, сервер работает в свои окна, и сохранённое число на его поведение не влияло бы. Поэтому запрос значит то, что говорит — число переводит сервер в режим «засыпает, когда нет запросов», null в «круглосуточно», и расписание в обоих случаях снимается вместе со сгенерированными им окнами пробуждения. Снятие видно полем data.workScheduleCleared. Окна, заведённые вручную, не затрагиваются; текущий режим сервера — поля runMode и workSchedule в GET /v1/infra/servers/:id.
• Эндпоинт не меняет статус — только обновляет конфигурацию. Чтобы усыпить сервер сразу, используйте POST /sleep-now.

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

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