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

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

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

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
  }
}

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

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 — переход в «Всегда онлайн» при включённых окнах пробуждения:

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

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

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