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

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

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

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

Если сервер стоит на вытесняемом (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
  }
}

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

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 на невытесняемом тарифе) при включённых окнах пробуждения:

{
  "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. Запросы, которые приложение отправляет само наружу, активностью не считаются, поэтому приложение с постоянным опросом внешнего API собственную машину в сети не удерживает и через фактический таймаут останавливается вместе с ней. Значение null отключает такой сон только без действующего расписания пробуждения.
• Авто-пробуждение сохраняется. Сервер, заснувший по таймеру, просыпается при вызове /deploy//wake//start, а обращение к HTTPS-субдомену будит его на условиях автоматического пробуждения.
• Значение по умолчанию для новых серверов — 60 минут. Текущее значение — в поле GET /v1/infra/servers/:id.
• Серверы агентов и управляемых ботов без расписания не засыпают по простою. Речь о машинах, которые платформа создаёт сама под AI-агента или управляемого бота, — в ответе GET /v1/infra/servers/:id у них поле createdVia равно agent или bot. Они создаются с sleepAfterMinutes: null, потому что спящий бот перестаёт опрашивать Битрикс24, не проснётся на новое сообщение, а выполняемая задача оборвётся. Запрос с числовым sleepAfterMinutes для такого сервера отклоняется — 400 AGENT_IDLE_SLEEP_FORBIDDEN; сохранённым значением остаётся только null. На вытесняемом тарифе включённое расписание пробуждения разрешено и включает платформенный таймаут после окна, поэтому null больше не означает круглосуточную работу. На невытесняемом тарифе создать или обновить расписание при null нельзя; fallback там применяется только к уже существующей комбинации настроек. Машина, созданная через POST /v1/infra/servers, имеет createdVia: api и под запрет числового таймаута не подпадает.
• ALWAYS_ON_CONFLICT защищает только режим «Всегда онлайн». На вытесняемом тарифе null совместим с расписанием: при действующем окне включается платформенный таймаут после окна. На невытесняемом тарифе правила асимметричны: запрос sleepAfterMinutes: null отклоняется, пока есть включённое окно пробуждения, а создание или обновление любого окна отклоняется, пока сохранён null, даже если в запросе передано enabled: false. Удаление окна разрешено. Для уже существующей комбинации null с действующим расписанием применяется платформенный таймаут после окна. Перед переходом в «Никогда» удалите или отключите включённые окна либо оставьте числовой таймаут.
• Эндпоинт не меняет статус — только обновляет конфигурацию. Чтобы усыпить сервер сразу, используйте POST /sleep-now.

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

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