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. How it interacts with wake-schedule windows is described below.

null disables idle auto-sleep. The .com plans are non-preemptible, so a dedicated machine with null outside the SCHEDULE run mode does not idle-sleep, even with previously stored windows. In the SCHEDULE run mode, the assigned work schedule determines sleep. Creating or updating wake windows normally requires an explicit numeric value (15, 30, 60, or 240).

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: the .com plans are non-preemptible, and writing null also removes an assigned work 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 “Runs around the clock” 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.
• 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 only the “Runs around the clock” mode. The rules are asymmetric: setting sleepAfterMinutes: null while wake-schedule windows are enabled is rejected, and creating or updating any window while null is stored is rejected even with enabled: false. The window-write gate excludes an app in a galaxy, which inherits the galaxy's plan, and a server in the SCHEDULE run mode. When writing null, the exception applies to the SCHEDULE run mode. Deleting a window is allowed. Previously stored windows do not enable idle auto-sleep for a dedicated machine with null outside the SCHEDULE run mode. Before switching to “Never”, delete or disable the enabled windows, 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 there are no requests", null to "Runs 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