#Усыпить сейчас

POST /v1/infra/servers/:id/sleep-now

Немедленно усыпляет работающий BLACKHOLE-сервер: виртуальная машина останавливается у провайдера, статус меняется на sleeping, рабочая биллинг-транзакция финализируется и открывается сонная (тариф sleep ниже). Полезно для разовой экономии, когда вы знаете, что сервер не понадобится в ближайшие часы. Для автоматической остановки через N минут простоя используйте `PATCH /sleep`.

#Параметры

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

#Примеры

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

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

#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/sleep-now

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

await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep-now`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

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

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

#Поля ответа

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

{ "success": true }

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

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

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

#Ошибки

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

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

• На OPEN-сервере используйте `/stop`. Функционально для BLACKHOLE /sleep-now и /stop эквивалентны, но /sleep-now помечен как BH-специфический и для OPEN вернёт BLACKHOLE_ONLY.
• Автоматическое пробуждение сохраняется. В отличие от административного блока (preventWake=true), ручной /sleep-now не ставит preventWake — сервер проснётся сам при обращении к HTTPS-субдомену или по вызову `/deploy`.
• Атомарный переход. База обновляется одним updateMany с фильтром status='RUNNING' — гонки двух одновременных вызовов приводят ко второму CONFLICT, а не к двойному списанию.

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

• Настроить авто-сон — PATCH /v1/infra/servers/:id/sleep — сервер засыпает сам через N минут.
• Остановить сервер — универсальная остановка (работает и для OPEN).
• Запустить сервер — пробудить из sleeping.
• Разбудить с ожиданием — POST /v1/infra/servers/:id/wake?wait=true — блокирующее пробуждение.

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

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

Настраивает таймер автоматического засыпания BLACKHOLE-сервера. При отсутствии HTTP-запросов или SSH-активности в течение sleepAfterMinutes минут сервер автоматически останавливается. При следующем обращении просыпается сам. Передача 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-обращения к приложению через туннель, активность на порту 22 (для OPEN-серверов) и exec-сессии Deploy API. Реальная активность проверяется раз в несколько минут через Gateway-метрики.
• Авто-пробуждение сохраняется. Сервер, заснувший по таймеру, автоматически просыпается при следующем HTTP-запросе к HTTPS-субдомену или при вызове `/deploy`/`/wake`/`/start`.
• Значение по умолчанию для новых серверов — 60 минут. Текущее значение — в поле `GET /v1/infra/servers/:id`.
• Агенты и managed-боты создают свои серверы с sleepAfterMinutes: null — они должны оставаться в сети круглосуточно, чтобы отвечать на сообщения. Для обычных приложений такая настройка тоже допустима, но приведёт к постоянному списанию по рабочему тарифу. По умолчанию агент/бот создаётся на вытесняемом тарифе (дешевле), который облако перезапускает ~раз в сутки; для непрерывной работы включите опцию «Всегда онлайн» при создании — она ставит агента/бота на невытесняемый тариф.
• Взаимное исключение с расписанием пробуждения. sleepAfterMinutes: null на невытесняемом тарифе означает «Всегда онлайн» — такой сервер несовместим с включёнными окнами пробуждения: запрос отклоняется с ALWAYS_ON_CONFLICT. Верно и обратное — окно нельзя объявить на сервере «Всегда онлайн». Сначала удалите или отключите окна, либо оставьте числовой таймаут.
• Эндпоинт не меняет статус — только обновляет конфигурацию. Чтобы усыпить сервер сразу, используйте `POST /sleep-now`.

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

• Усыпить сейчас — немедленная остановка, не дожидаясь таймера.
• Запустить сервер — пробудить из sleeping.
• Тарифы провайдера — поле sleepPriceMonthly показывает тариф в режиме сна.
• Получить сервер — проверить текущее значение sleepAfterMinutes.