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

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

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

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера в режиме BLACKHOLE

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

Поле Тип Обяз. Описание
sleepAfterMinutes number | null да Таймаут простоя в минутах. Допустимые значения: 15, 30, 60, 240, или null (для отключения авто-сна). Другие значения отклоняются с VALIDATION_ERROR

#Примеры

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

Terminal 
# Включить авто-сон через 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-приложение

Terminal 
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 — личный ключ

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-приложение

javascript 
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 boolean Всегда true при успехе
data.sleepAfterMinutes number | null Актуальное значение таймаута (эхо переданного)

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

JSON 
{
  "success": true,
  "data": {
    "sleepAfterMinutes": 60
  }
}

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

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

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

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

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

#Ошибки

HTTP Код Описание
400 VALIDATION_ERROR sleepAfterMinutes не в списке [15, 30, 60, 240, null]
400 BLACKHOLE_ONLY Сервер в режиме OPEN — авто-сон недоступен
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

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

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

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

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