#Scheduled wake

Recurring wake windows for a server in BLACKHOLE mode: the platform brings the server up by a given cron-expressed moment, and the task itself is fired by the app's own cron once the machine is already 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 by the window's moment, and the window can be skipped. The create and update response carries preemptibleAdvisoryCode: "PREEMPTIBLE_BEST_EFFORT" for exactly this case — see Create a window. For time-critical tasks, use a non-preemptible plan or the always-on (24/7) mode.

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 apart from this CRUD, else the platform default — currently 180 seconds. For a server with kind: "GALAXY_APP", waking runs in two phases — bringing up the host and starting the container — so budget lead up to 900 seconds.

#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 app

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 app

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 behavior

• Check order. The key's scope and server ownership are checked before the other gates, so WAKE_SCHEDULE_DISABLED/BLACKHOLE_ONLY/GALAXY_NOT_SUPPORTED/ALWAYS_ON_CONFLICT only ever surface for a request with a valid key against an owned, existing server. The cron-expression checks (VALIDATION_ERROR, then CADENCE_TOO_LOW) run after these gates.
• tzWarning/tzWarningCode are a conservative heuristic. The platform doesn't track whether the server was actually 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, "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' value — on a preemptible plan the platform does not forbid a schedule (that's its intended use case), it only honestly reports that waking by the window's moment is best-effort. Localize on the preemptibleAdvisoryCode code, not on the preemptibleAdvisory string — that is a fixed English string for non-UI clients, not meant to be shown to a user as-is.
• The platform does not configure the cron inside the VM. POST /wake-schedules only guarantees the server is up by the target moment (best-effort on a preemptible plan — see preemptibleAdvisoryCode above). Firing the task at that moment is the app's own cron/timer's job.

#See also

• List windows
• Update a window
• Delete a window
• What the app receives — deploy timezone and the in-VM cron