Set the server run mode

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

Switches a BLACKHOLE server to one of three run modes: it sleeps when there are no requests, runs on a schedule, or runs around the clock. The mode decides what the server costs, so the request either applies in full or is refused with nothing changed.

Until run modes are enabled for the Bitrix24 account, the request is refused with 400 RUN_MODE_UNAVAILABLE. The current mode is always readable — the runMode and workSchedule fields in GET /v1/infra/servers/:id.

Parameters

Request fields (body)

The body is one of three shapes, chosen by the mode field. A field the chosen shape does not take is refused with VALIDATION_ERROR rather than dropped.

Examples

curl — personal key

curl -X PATCH https://vibecode.bitrix24.com/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 application

curl -X PATCH https://vibecode.bitrix24.com/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 — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/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(`Mode: ${data.runMode}, next wake-up: ${data.nextScheduledWakeAt}`)

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/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()

Response fields

The response carries the run-mode fields read after the write. The same shape comes in GET /v1/infra/servers/:id.

Response example

{
  "success": true,
  "data": {
    "runMode": "SCHEDULE",
    "sleepAfterMinutes": 30,
    "workSchedule": {
      "id": "cmfp4r0q2000a1ocg7h2k9x3d",
      "name": "Warehouse shifts",
      "presetKey": null,
      "timezone": "Europe/Berlin",
      "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-21T06:51:00.000Z"
  }
}

Error response example

400 — idle sleep requested for an agent server:

{
  "success": false,
  "error": {
    "code": "AGENT_IDLE_SLEEP_FORBIDDEN",
    "message": "idle sleep is not available for agents and bots: they must stay reachable"
  }
}

Errors

Full list of shared error codes — Errors.

Known specifics

• A schedule outranks the idle threshold. While a schedule is assigned, the server runs during its windows and sleeps after them, and the stored sleepAfterMinutes does not apply. Switching to SCHEDULE does not erase the threshold: if the schedule is later deleted with consent to move its machines, the app returns to IDLE with exactly this number — see Delete a schedule.
• Schedule windows become server wake-ups. The platform brings the server up ahead of each window, and after the window ends the server falls asleep on the platform idle timeout. These wake-ups do not show in the wake window list and are not edited there — the schedule itself changes them. Windows created by hand are not touched by the run mode.
• A request outside a window still wakes the server. A request to the HTTPS subdomain wakes a sleeping server outside the schedule windows too — on the automatic wake-up conditions. That running time is billed at the running-machine rate.
• A galaxy app takes a run mode like a standalone server. A galaxy sleeps only when all of its apps sleep. A schedule for one of two agents saves nothing while the other runs around the clock: set the mode on every app that must not keep the galaxy awake.
• A write through /sleep removes the schedule. A number in sleepAfterMinutes moves the server to IDLE, null to ALWAYS, and the assigned schedule is removed in both cases.

See also

• Configure auto-sleep
• Work schedule library
• Get a server
• Scheduled wake