Configure auto-sleep

PATCH /v1/infra/servers/:id/sleep

Configures the stored automatic sleep timer of a BLACKHOLE server. If no inbound HTTP requests reach the application for the effective timeout, the server stops automatically. It can be brought back up by a /wake call, though a request to the HTTPS subdomain does not always wake the server — see that page for the conditions. Passing null stores the “Never” setting and enables guaranteed always-on mode. This endpoint rejects null while wake-schedule windows are enabled, unless the server is in the SCHEDULE run mode. Creating or updating a schedule is rejected whenever null is stored, even for a disabled window, except for an app in a galaxy and a server in the SCHEDULE run mode. If an older record already contains null plus an effective schedule, the effective timeout changes between windows — see below.

Without an effective schedule, null disables idle auto-sleep. Setting null while enabled windows exist is rejected as an always-on conflict, unless the server is in the SCHEDULE run mode. In the other direction, creating or updating any window while null is stored is rejected, even when that window is disabled, except for an app in a galaxy and a server in the SCHEDULE run mode. If an older record already contains null plus an enabled and entitled schedule with a next wake, the platform applies its post-window timeout — 15 minutes of inactivity by default. An explicit numeric value (15, 30, 60, or 240) remains compatible with a schedule and always takes priority over that fallback.

A server with idleSleepProtected: true must stay reachable, so a numeric threshold is refused with 400 AGENT_IDLE_SLEEP_FORBIDDEN. This is an agent or bot server, or an ordinary application with an enabled fetch bot. null and the scheduled run mode remain available.

For a continuous 24/7 workload, store null and leave no effective wake schedule. See Provider plans for the available plans and their characteristics.

Parameters

Request fields (body)

Examples

curl — personal key

# Enable auto-sleep after 60 minutes of inactivity
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'

# Disable auto-sleep
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": null}'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: 60 }),
  }
)
const { data } = await res.json()
console.log(`Auto-sleep after ${data.sleepAfterMinutes} min`)

JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: null }),
  }
)

Response fields

Response example

{
  "success": true,
  "data": {
    "sleepAfterMinutes": 60,
    "workScheduleCleared": false
  }
}

Error response example

400 — attempting to enable guaranteed always-on mode (null) while wake-schedule windows are enabled, if the server is not in the SCHEDULE run mode:

{
  "success": false,
  "error": {
    "code": "ALWAYS_ON_CONFLICT",
    "message": "The server has enabled wake-schedule windows, which conflict with always-on (24/7) mode. Delete or disable the wake windows first, or keep a sleep timeout."
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• What counts as activity and resets the timer. Inbound HTTP requests that reach the application through the tunnel reset the timer. Actual activity is checked every few minutes through Gateway metrics, and the moment of the last request is exposed as lastRequestAt by GET /v1/infra/servers/:id/metrics. Outbound requests made by the application do not count as activity. The platform separately protects an application with an enabled fetch bot: it has idleSleepProtected: true, a numeric threshold is unavailable, and outbound polling does not have to imitate inbound traffic. For other applications, outbound polling does not keep the machine online. null disables this sleep only without an effective wake schedule.
• Auto-wake is preserved. A server put to sleep by the timer wakes on a call to /deploy//wake//start, and a request to the HTTPS subdomain wakes it under the automatic wake conditions.
• The default value for new servers is 60 minutes. The current value is returned by GET /v1/infra/servers/:id.
• Agent servers, managed-bot servers, and applications with an enabled fetch bot do not idle-sleep without a schedule. Machines created by the platform for an AI agent or managed bot have createdVia set to agent or bot. An ordinary server or Galaxy application has the same protection while an enabled fetch bot is associated with it. In every case GET /v1/infra/servers/:id returns idleSleepProtected: true, and a numeric sleepAfterMinutes request is rejected with 400 AGENT_IDLE_SLEEP_FORBIDDEN. An ordinary application's previously stored threshold is kept and takes effect again after its last fetch bot is disabled. A schedule remains available and outranks protection. A webhook Bot alone does not enable protection.
• ALWAYS_ON_CONFLICT protects guaranteed always-on mode. Current writes enforce the conflict in two directions: setting null while wake-schedule windows are enabled is rejected, and creating or updating any window while null is stored is rejected even when that window is disabled. There are two exceptions: an app in a galaxy — it does not choose its plan but inherits it from the galaxy — and a server in the SCHEDULE run mode: its sleep is declared by the schedule. Neither is refused because null is stored. Deleting a window is allowed. Existing older records are not rewritten: if one already contains both settings, an effective schedule activates the platform's post-window timeout. Delete or disable the windows first, or keep a numeric timeout.
• Writing the timeout clears an assigned work schedule. A schedule outranks the timeout: while one is assigned the server runs during its windows, and the stored number would not affect its behavior at all. So the request means what it says — a number moves the server to "sleeps when idle", null to "around the clock", and either one drops the schedule together with the wake windows it generated. data.workScheduleCleared tells you it happened. Windows created by hand are untouched. The server's current mode is shown in the runMode and workSchedule fields of GET /v1/infra/servers/:id.
• The endpoint does not change the status — it only updates the configuration. To put the server to sleep immediately, use POST /sleep-now.

See also

• Sleep now
• Start the server
• Server metrics
• Provider plans
• Get a server