#Пробуждение по расписанию

Повторяющиеся окна пробуждения для сервера в режиме BLACKHOLE: платформа поднимает сервер к заданному моменту по cron-выражению, а саму задачу запускает собственный cron внутри уже поднятой машины — платформа не читает и не выполняет код приложения.

На вытесняемом тарифе подъём — best-effort, не гарантия. Сервер такого типа поднимается по мере освобождения ёмкости — через очередь, — поэтому к моменту окна свободного места может не оказаться, и окно может быть пропущено. Ответ создания и обновления окна несёт поле preemptibleAdvisoryCode: "PREEMPTIBLE_BEST_EFFORT" именно для этого случая — см. Создать окно. Для задач, критичных ко времени, используйте невытесняемый тариф или режим «Всегда онлайн (24/7)».

Скоуп: vibe:infra

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

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

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

#Параметры

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

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

#Примеры

#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/ALWAYS_ON_CONFLICT увидит только запрос с корректным ключом на существующий свой сервер. Проверка cron-выражения (VALIDATION_ERROR, затем CADENCE_TOO_LOW) идёт после этих гейтов.
• tzWarning/tzWarningCode — консервативная эвристика. Платформа не хранит, был ли сервер передеплоен после объявления окна, поэтому предупреждение приходит при любом наборе активных окон после мутации — даже если таймзона уже верно проставлена в переменных окружения. Ориентируйтесь на код: "SINGLE_ZONE" — таймзона однозначна и попадёт в TZ при следующем деплое, "MULTI_ZONE" — окна в разных поясах, TZ не проставляется автоматически.
• preemptibleAdvisoryCode/preemptibleAdvisory — не гейт, а предупреждение. Окно создаётся или обновляется независимо от значения этих полей — на вытесняемом тарифе платформа не запрещает расписание (это её целевой сценарий), а лишь честно сообщает, что подъём к моменту окна best-effort. Локализуйте по коду preemptibleAdvisoryCode, а не по строке preemptibleAdvisory — это фиксированная английская строка для не-UI-клиентов, не предназначенная для показа пользователю как есть.
• Cron внутри VM платформа не настраивает. POST /wake-schedules только гарантирует, что сервер поднят к нужному моменту (на вытесняемом тарифе — best-effort, см. preemptibleAdvisoryCode выше). Запуск задачи в этот момент — ответственность собственного cron/таймера внутри приложения.

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

• Список окон
• Обновить окно
• Удалить окно
• Что приходит в приложение — таймзона деплоя и in-VM cron