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 determines what the server costs, so the request is either applied in full or refused with nothing changed.

If run modes are not 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. If the body contains a field that the selected shape does not accept, the request is rejected with VALIDATION_ERROR rather than the field being silently ignored.

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",
    "idleSleepProtected": false,
    "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 a server that must stay reachable:

{
  "success": false,
  "error": {
    "code": "AGENT_IDLE_SLEEP_FORBIDDEN",
    "message": "idle sleep is not available while the server must stay reachable"
  }
}

Errors

For the full list of shared API error codes, see 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, an ordinary app returns to IDLE with exactly this number, while a protected app stays in effective ALWAYS mode with the same remembered threshold — 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 goes to sleep when the platform idle timeout expires. These wake-ups do not appear 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 — under the automatic wake 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