Scheduled wake

Recurring wake windows for a server in BLACKHOLE mode: the platform starts bringing the server up ahead of the moment set by a cron expression, with a margin for boot, and the task itself is fired by the app's own cron once the machine is up — the platform never reads or runs the app's code.

On a preemptible plan, waking is best-effort, not a guarantee. A server of this type comes up as capacity frees up — through a queue — so there may be no free capacity when the window comes, and the window can be skipped. The create and update responses carry preemptibleAdvisoryCode: "PREEMPTIBLE_BEST_EFFORT" for exactly this case — see Create a window. On a non-preemptible plan, too, the server is not guaranteed to be up by the exact moment: a boot can take several minutes longer. Write a time-critical task so that, once the server starts, it checks whether its run time has already passed and, if so, runs late — or keep the server in the “Always online (24/7)” mode.

A deploy changes neither the windows nor the sleep timer. The wake schedule and the auto-sleep timer are stored on the platform, not in the application code, so shipping a new version does not reset them — the windows keep working with no extra action. The only thing the deploy takes from the schedule is the windows' timezone: on a dedicated virtual machine it lands in the TZ environment variable when every enabled window declares the same zone. Details — Full application deploy.

Creating or updating a wake schedule normally requires a numeric auto-sleep setting. Creating or updating any window while sleepAfterMinutes is null (“Never”) is rejected as an always-on conflict, even when that window is disabled. In the reverse direction, setting null is rejected only while an enabled window exists and the server is not in the SCHEDULE run mode; existing disabled windows neither affect the timeout nor block that sleep-setting change. An explicit numeric sleepAfterMinutes remains the effective timeout and is not shortened by the schedule. Existing older records are not rewritten: if one already contains null plus an enabled and entitled schedule with a computed next wake, the platform's post-window timeout applies — 15 minutes of inactivity by default. When there are no effective windows, null once again means no idle auto-sleep. Creating or updating a window with null is not rejected for an app in a galaxy: the app does not choose its plan but inherits it from the galaxy. Nor is it rejected for a server in the SCHEDULE run mode: its sleep is declared by the schedule.

Scope: vibe:infra

Create a wake window

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

Declares a new recurring wake window for a server in BLACKHOLE mode. The body is a flat object, with no fields wrapper.

Parameters

Request fields (body)

The lead margin resolves in three tiers: the window's own value, else a server-level margin set outside this CRUD, else the platform margin. The platform margin is also a floor: a smaller value is stored on the window as sent, but the wake still starts no later than the platform margin before the cronExpr moment. For a server with kind: "GALAXY_APP", the platform margin is larger than for a standalone server: waking runs in two phases — bringing up the host and starting the container.

This schedule write requires a numeric auto-sleep setting. If the server stores sleepAfterMinutes: null (“Never”), the request is rejected as an always-on conflict even when enabled is false. In the reverse direction, setting null is rejected only while an enabled window exists and the server is not in the SCHEDULE run mode; an already stored disabled window neither affects the timeout nor blocks that sleep-setting change. An explicit numeric value remains the effective timeout and is not shortened by the schedule. Existing older records are not rewritten: if one already contains null plus an effective schedule, the platform's post-window fallback applies — 15 minutes of inactivity by default. Creating or updating a window with null is not rejected for an app in a galaxy: the app does not choose its plan but inherits it from the galaxy. Nor is it rejected for a server in the SCHEDULE run mode: its sleep is declared by the schedule.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/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": "America/New_York",
    "label": "daily report",
    "enabled": true
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/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": "America/New_York",
    "label": "daily report",
    "enabled": true
  }'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/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: 'America/New_York',
      label: 'daily report',
      enabled: true,
    }),
  }
)
const body = await res.json()
if (body.tzWarningCode === 'MULTI_ZONE') {
  console.warn('Windows span more than one timezone — TZ is not injected at deploy time')
}

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/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: 'America/New_York',
      label: 'daily report',
      enabled: true,
    }),
  }
)

Response fields

tzWarning, tzWarningCode, preemptibleAdvisoryCode, and preemptibleAdvisory are top-level response fields, not nested under data.

Response example

The server's only active window — the timezone is unambiguous:

{
  "success": true,
  "data": {
    "id": "cm38x02qp0001ml08g7k3h2a",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "cronExpr": "0 9 * * 1-5",
    "timezone": "America/New_York",
    "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
}

A server on a preemptible plan would get "preemptibleAdvisoryCode": "PREEMPTIBLE_BEST_EFFORT" and a non-empty preemptibleAdvisory instead of null in those same two fields — the rest of the response shape is unchanged.

Error response example

400 — the window conflicts with an always-on server:

{
  "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."
  }
}

Errors

Full list of shared error codes — Errors.

Known specifics

• Check order. The key's scope and server ownership are checked before the other conditions, so WAKE_SCHEDULE_DISABLED/BLACKHOLE_ONLY/GALAXY_NOT_SUPPORTED/WAKE_SCHEDULE_GALAXY_DISABLED/ALWAYS_ON_CONFLICT only ever surface for a request with a valid key against an owned, existing server, and among themselves these conditions are checked in the order listed. The cron-expression checks (VALIDATION_ERROR, then CADENCE_TOO_LOW) run after these gates.
• Two different galaxy refusals. GALAXY_NOT_SUPPORTED is about the galaxy host: it holds no windows at all, and enabling the capability will not change that. WAKE_SCHEDULE_GALAXY_DISABLED is about an app inside a galaxy: it can hold windows, but the capability for such apps is switched off on the platform. The first arrives with status 400, the second with 403, so branch on the response code.
• tzWarning/tzWarningCode are a conservative heuristic. The platform does not track whether the application was redeployed since a window was declared, so the advisory fires for any set of active windows after a mutation — even when the timezone is already correctly set in the environment. Go by the code: "SINGLE_ZONE" means the timezone is unambiguous and lands in TZ on the next deploy of a dedicated virtual machine, "MULTI_ZONE" means the windows span more than one zone and TZ is not auto-injected.
• preemptibleAdvisoryCode/preemptibleAdvisory are an advisory, not a gate. The window is created or updated regardless of these fields' values — on a preemptible plan the platform does not forbid a schedule (that is its intended use case); it only states up front that waking the server in time for the window is best-effort. Localize by preemptibleAdvisoryCode, not by the preemptibleAdvisory string — that is a fixed English string for non-UI clients, not meant to be shown to a user as-is.
• null in the sleep setting normally blocks schedule creation and update. It is the stored “Never” choice and disables idle auto-sleep; creating or updating a window while it is stored is rejected as an always-on conflict, even when the submitted window is disabled. Setting null through the sleep endpoint is narrower: that write is rejected only while an enabled window exists and the server is not in the SCHEDULE run mode. If an older record already contains null plus an effective schedule, the platform's post-window timeout applies between windows. V1 does not return the computed session policy: for long-running background work, keep null with no enabled windows or choose a numeric timeout long enough for the task. Creating or updating a window with null is not rejected for an app in a galaxy: the app does not choose its plan but inherits it from the galaxy. Nor is it rejected for a server in the SCHEDULE run mode: its sleep is declared by the schedule.
• The platform does not configure the cron inside the VM. POST /wake-schedules only brings the server up for the target moment — ahead of time, with a margin for boot, but with no guarantee it is up in time. On a preemptible plan the window can be skipped entirely — see preemptibleAdvisoryCode above. Firing the task at that moment is the job of the app's own cron/timer.

See also

• List windows
• Update a window
• Delete a window
• What the app receives