Сменить режим работы сервера

PATCH /v1/infra/servers/:id/run-mode

Переводит BLACKHOLE-сервер в один из трёх режимов работы: засыпает, когда нет запросов, работает по расписанию или работает круглосуточно. Режим определяет счёт за сервер, поэтому запрос либо выполняется целиком, либо отклоняется, ничего не изменив.

Если режимы работы не подключены для портала, запрос отклоняется с 400 RUN_MODE_UNAVAILABLE. Текущий режим при этом читается всегда — поля runMode и workSchedule в GET /v1/infra/servers/:id.

Параметры

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

Тело — одна из трёх форм, выбранная полем mode. Поле, которое выбранная форма не принимает, отклоняется с VALIDATION_ERROR, а не отбрасывается.

Примеры

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

curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/run-mode \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "SCHEDULE", "scheduleId": "WORK_SCHEDULE_ID"}'

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

curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/run-mode \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "SCHEDULE", "scheduleId": "WORK_SCHEDULE_ID"}'

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/run-mode`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ mode: 'SCHEDULE', scheduleId: workScheduleId }),
  }
)
const { data } = await res.json()
console.log(`Режим: ${data.runMode}, ближайшее пробуждение: ${data.nextScheduledWakeAt}`)

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/run-mode`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ mode: 'SCHEDULE', scheduleId: workScheduleId }),
  }
)
const { data } = await res.json()

Поля ответа

Ответ — поля режима, прочитанные после записи. Та же форма приходит в GET /v1/infra/servers/:id.

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

{
  "success": true,
  "data": {
    "runMode": "SCHEDULE",
    "idleSleepProtected": false,
    "sleepAfterMinutes": 30,
    "workSchedule": {
      "id": "cmfp4r0q2000a1ocg7h2k9x3d",
      "name": "Смены склада",
      "presetKey": null,
      "timezone": "Europe/Moscow",
      "windows": [
        { "isoDay": 1, "start": "09:00", "end": "18:00" },
        { "isoDay": 2, "start": "09:00", "end": "13:00" },
        { "isoDay": 2, "start": "14:00", "end": "24:00" }
      ]
    },
    "nextScheduledWakeAt": "2026-09-21T05:51:00.000Z"
  }
}

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

400 — сон по простою запрошен для сервера, который должен оставаться на связи:

{
  "success": false,
  "error": {
    "code": "AGENT_IDLE_SLEEP_FORBIDDEN",
    "message": "idle sleep is not available while the server must stay reachable"
  }
}

Ошибки

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

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

• Расписание сильнее порога простоя. Пока серверу назначено расписание, он работает в его окна и засыпает после них, а сохранённый sleepAfterMinutes не действует. При переходе в SCHEDULE порог не стирается. Если расписание потом удалят с согласием на перевод машин, обычное приложение вернётся в IDLE именно с этим числом, а защищённое останется в эффективном ALWAYS с тем же запомненным порогом — см. Удалить расписание.
• Окна расписания превращаются в пробуждения сервера. Платформа поднимает сервер к началу каждого окна с опережением, а после конца окна сервер засыпает по платформенному таймауту простоя. Эти пробуждения не видны в списке окон пробуждения и не правятся через него — их меняет само расписание. Окна, заведённые вручную, режим не затрагивает.
• Запрос вне окна тоже будит сервер. Обращение к HTTPS-субдомену будит спящий сервер и вне окон расписания — на условиях автоматического пробуждения. Время такой работы оплачивается по ставке работающей машины.
• Приложение галактики получает режим, как отдельный сервер. Галактика засыпает, только когда спят все её приложения. Расписание одному агенту из двух ничего не экономит, пока второй работает круглосуточно: режим задаётся всем приложениям, которые не должны держать галактику включённой.
• Запись через /sleep снимает расписание. Число в sleepAfterMinutes переводит сервер в IDLE, null — в ALWAYS, и назначенное расписание в обоих случаях снимается.

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

• Настроить авто-сон
• Библиотека расписаний
• Получить сервер
• Пробуждение по расписанию