Создать окно пробуждения

POST /v1/infra/servers/:id/wake-schedules

Объявляет новое повторяющееся окно пробуждения для сервера в режиме BLACKHOLE. Тело передаётся плоским объектом, без обёртки fields.

Параметры

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

Запас lead разрешает три уровня: значение самого окна, иначе запас сервера, заданный отдельно от этого раздела CRUD, иначе запас платформы. Запас платформы служит и нижней границей: меньшее значение сохраняется в окне как передано, но подъём всё равно начинается не позже, чем за платформенный запас до момента cronExpr. У сервера kind: "GALAXY_APP" запас платформы больше, чем у отдельной машины: пробуждение проходит два этапа — подъём хоста и старт контейнера.

Включённое окно влияет и на авто-сон. На вытесняемом тарифе при сохранённом sleepAfterMinutes: null («Никогда») после расчёта следующего пробуждения фактическим таймаутом становится платформенный запас после окна — по умолчанию 15 минут простоя. На невытесняемом тарифе создание или обновление окна при null отклоняется даже с enabled: false. Платформенный таймаут после окна там возможен только для уже существующей комбинации настроек. Явно заданное число остаётся фактическим таймаутом и расписанием не сокращается. Отключённое окно эту политику не меняет. Отказ при null на невытесняемом тарифе к приложению в галактике не относится: тариф оно не выбирает, а наследует от галактики. Не относится он и к серверу в режиме работы SCHEDULE: сон у него объявлен расписанием.

Примеры

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake-schedules" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpr": "0 9 * * 1-5",
    "timezone": "Europe/Moscow",
    "label": "daily report",
    "enabled": true
  }'

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake-schedules" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cronExpr": "0 9 * * 1-5",
    "timezone": "Europe/Moscow",
    "label": "daily report",
    "enabled": true
  }'

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/wake-schedules`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      cronExpr: '0 9 * * 1-5',
      timezone: 'Europe/Moscow',
      label: 'daily report',
      enabled: true,
    }),
  }
)
const body = await res.json()
if (body.tzWarningCode === 'MULTI_ZONE') {
  console.warn('Окна расходятся по часовым поясам — TZ в деплое не проставляется')
}

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

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/wake-schedules`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      cronExpr: '0 9 * * 1-5',
      timezone: 'Europe/Moscow',
      label: 'daily report',
      enabled: true,
    }),
  }
)

Поля ответа

tzWarning, tzWarningCode, preemptibleAdvisoryCode и preemptibleAdvisory — поля верхнего уровня ответа, не вложены в data.

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

Единственное активное окно сервера — часовой пояс однозначен:

{
  "success": true,
  "data": {
    "id": "cm38x02qp0001ml08g7k3h2a",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "cronExpr": "0 9 * * 1-5",
    "timezone": "Europe/Moscow",
    "label": "daily report",
    "lead": null,
    "enabled": true,
    "source": "MANUAL",
    "lastFiredAt": null,
    "wakeAttemptStartedAt": null,
    "lastWakeLateAt": null,
    "createdAt": "2026-07-10T08:12:00.000Z",
    "updatedAt": "2026-07-10T08:12:00.000Z"
  },
  "tzWarning": "The VM may have been deployed with a different timezone (or not redeployed since this window was declared) — verify the in-VM cron or redeploy the app so TZ is re-injected.",
  "tzWarningCode": "SINGLE_ZONE",
  "preemptibleAdvisoryCode": null,
  "preemptibleAdvisory": null
}

Сервер на вытесняемом тарифе получил бы "preemptibleAdvisoryCode": "PREEMPTIBLE_BEST_EFFORT" и непустой preemptibleAdvisory вместо null в тех же двух полях — остальная форма ответа не меняется.

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

400 — окно нарушает гарантию сервера «Всегда онлайн»:

{
  "success": false,
  "error": {
    "code": "ALWAYS_ON_CONFLICT",
    "message": "Scheduled wake conflicts with an always-on (24/7) server, which never auto-sleeps. Turn off the always-on toggle, or set a sleep timeout instead of \"Never\", to schedule wake windows."
  }
}

Ошибки

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

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

• Порядок проверок. Скоуп ключа и владение сервером проверяются раньше остальных условий, поэтому WAKE_SCHEDULE_DISABLED/BLACKHOLE_ONLY/GALAXY_NOT_SUPPORTED/WAKE_SCHEDULE_GALAXY_DISABLED/ALWAYS_ON_CONFLICT увидит только запрос с корректным ключом на существующий свой сервер, а между собой эти условия проверяются в перечисленном порядке. Проверка cron-выражения (VALIDATION_ERROR, затем CADENCE_TOO_LOW) идёт после этих гейтов.
• Два разных отказа по галактике. GALAXY_NOT_SUPPORTED относится к хосту галактики: он окон не держит вовсе, и включение возможности этого не изменит. WAKE_SCHEDULE_GALAXY_DISABLED относится к приложению внутри галактики: окна оно держать умеет, но на платформе выключена возможность для таких приложений. Первый приходит со статусом 400, второй — с 403, и ветвить логику стоит по коду ответа.
• tzWarning/tzWarningCode — консервативная эвристика. Платформа не хранит, выкладывали ли приложение заново после объявления окна, поэтому предупреждение приходит при любом наборе активных окон после мутации — даже если часовой пояс уже верно проставлен в переменных окружения. Ориентируйтесь на код: "SINGLE_ZONE" — часовой пояс однозначен и попадёт в TZ при следующем деплое отдельной виртуальной машины, "MULTI_ZONE" — окна в разных поясах, TZ не проставляется автоматически.
• preemptibleAdvisoryCode/preemptibleAdvisory — не гейт, а предупреждение. Окно создаётся или обновляется независимо от значения этих полей — на вытесняемом тарифе платформа не запрещает расписание (это её целевой сценарий), а лишь честно сообщает, что подъём к моменту окна best-effort. Локализуйте по коду preemptibleAdvisoryCode, а не по строке preemptibleAdvisory — это фиксированная английская строка для не-UI-клиентов, не предназначенная для показа пользователю как есть.
• null в настройке сна не отменяет сон при действующем расписании. На вытесняемом тарифе это сочетание разрешено: значение остаётся сохранённым выбором «Никогда», но между окнами применяется платформенный таймаут после окна. На невытесняемом тарифе текущий запрос создания или обновления окна при null отклоняется. Платформенный таймаут после окна там возможен только у уже существующей комбинации настроек. API V1 не возвращает вычисленный session-policy: если автоматизация зависит от длительной фоновой работы, задайте явный числовой таймаут или не оставляйте действующих окон. Отказ при null на невытесняемом тарифе к приложению в галактике не относится: тариф оно не выбирает, а наследует от галактики. Не относится он и к серверу в режиме работы SCHEDULE: сон у него объявлен расписанием.
• Cron внутри VM платформа не настраивает. POST /wake-schedules только поднимает сервер к нужному моменту — заранее, с запасом на загрузку, но без гарантии успеть к сроку. На вытесняемом тарифе окно может быть пропущено целиком, см. preemptibleAdvisoryCode выше. Запуск задачи в этот момент — ответственность собственного cron/таймера внутри приложения.

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

• Список окон
• Обновить окно
• Удалить окно
• Что приходит в приложение