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. The sleep endpoint rejects null while wake-schedule windows are enabled; schedule creation and update are rejected whenever null is stored, even for a disabled window. 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. In the other direction, creating or updating any window while null is stored is rejected, even when that window is disabled. 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.

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
  }
}

Error response example

400 — invalid sleepAfterMinutes value:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sleepAfterMinutes must be 15, 30, 60, 240, or null"
  }
}

400 — the server is not in BLACKHOLE mode:

{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Sleep settings are only available for BLACKHOLE servers"
  }
}

400 — attempting to enable guaranteed always-on mode while wake-schedule windows are enabled:

{
  "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 that the application itself makes do not count as activity, so an application built around continuously polling an external API does not keep its own machine online — after the effective timeout the machine stops, and the application with it. Delete or disable enabled wake windows before setting null to prevent that idle sleep. If an older record already contains null plus an effective schedule, the platform's post-window timeout still applies.
• 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 and managed-bot servers do not normally idle-sleep. This covers machines the platform creates itself for an AI agent or a managed bot — in the GET /v1/infra/servers/:id response their createdVia field is agent or bot. They are created with sleepAfterMinutes: null because a sleeping bot stops polling Bitrix24, will not wake on a new message, and interrupts any task in progress. A numeric sleepAfterMinutes request for such a server is rejected with 400 AGENT_IDLE_SLEEP_FORBIDDEN; null is the only stored value, and schedule creation or update is rejected while it is stored, even for a disabled window. If an older record already contains null plus an effective schedule, the platform's post-window timeout applies and null no longer means around-the-clock operation. A machine created through POST /v1/infra/servers has createdVia: api and is not covered by the numeric-timeout restriction.
• 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. 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.
• 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