#Sleep now

POST /v1/infra/servers/:id/sleep-now

Immediately puts a running BLACKHOLE server to sleep: the virtual machine is stopped at the provider, the status changes to sleeping, the active billing transaction is finalized, and a sleep transaction is opened (the sleep tariff is lower). Useful for one-off savings when you know the server won't be needed for the next few hours. For automatic stop after N minutes of inactivity, use PATCH /sleep.

#Parameters

The request body is empty.

#Examples

#curl — personal key

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep-now

#curl — OAuth application

curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep-now

#JavaScript — personal key

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/sleep-now`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)

#JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/sleep-now`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

#Response fields

#Response example

The server was moved to sleeping:

{ "success": true }

Sleep deferred — the next scheduled wake window is already due:

{
  "success": true,
  "data": {
    "slept": false,
    "reason": "WAKE_IMMINENT"
  }
}

#Error response example

400 — server not in BLACKHOLE:

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

#Errors

Full list of common API errors — Errors.

#Known specifics

• On an OPEN server, use /stop. Functionally /sleep-now and /stop are equivalent for BLACKHOLE, but /sleep-now is marked as BH-specific and returns BLACKHOLE_ONLY for OPEN.
• Automatic wake is preserved. Unlike the administrative block (preventWake=true), a manual /sleep-now does not set preventWake — the server wakes by itself when its HTTPS subdomain is accessed or via a /deploy call.
• Agent and bot servers keep a wake block. For a server created through an agent or a bot, a manual call sets preventWake: true with the reason AGENT_STOPPED or BOT_STOPPED — only the /start of the matching card can wake it. Plain servers get no block.
• Atomic transition. The database is updated with a single updateMany filtered by status='RUNNING' — a race between two concurrent calls results in a CONFLICT for the second one, not a double charge.
• A server with a scheduled-wake window can defer sleep. The WAKE_IMMINENT branch applies only to a server that has a scheduled wake window. The platform compares the next window against the current moment: if it falls within the platform margin (5 minutes by default) or has just passed, sleep is cancelled so the platform does not shut the machine down right before it has to bring it back up. The response arrives with status 200 and the fields slept: false, reason: "WAKE_IMMINENT" — the server stayed in running. Repeat the call once the window has been served. For a server with no windows, and for a Bitrix24 account that has no access to scheduled wake, this branch never fires: the server goes to sleep straight away.

#See also

• Configure auto-sleep — PATCH /v1/infra/servers/:id/sleep — the server sleeps by itself after N minutes.
• Stop the server — universal stop (works for OPEN too).
• Start the server — wake from sleeping.
• Wake with waiting — POST /v1/infra/servers/:id/wake?wait=true — blocking wake.

#Configure auto-sleep

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

Configures the automatic sleep timer of a BLACKHOLE server. If there are no HTTP requests or SSH activity for sleepAfterMinutes minutes, the server stops automatically. On the next request it wakes up automatically. Passing null disables auto-sleep.

null disables the idle auto-sleep only — the server is no longer stopped for inactivity, and the plan does not change that. It can still be stopped by billing or access enforcement, or by an explicit lifecycle call. 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:

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

400 — switching to always-on 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. HTTP requests to the application through the tunnel, activity on port 22 (for OPEN servers), and Deploy API exec sessions. Real activity is checked once every few minutes via Gateway metrics.
• Auto-wake is preserved. A server put to sleep by the timer wakes automatically on the next HTTP request to the HTTPS subdomain or on a call to /deploy//wake//start.
• The default value for new servers is 60 minutes. The current value is returned by GET /v1/infra/servers/:id.
• Agents and managed bots create their servers with sleepAfterMinutes: null — they must stay online around the clock to respond to messages. The same setting is also allowed for regular applications, but the server is then billed at the full running rate around the clock.
• Mutual exclusion with the wake schedule. sleepAfterMinutes: null means always-on (24/7) — such a server is incompatible with enabled wake-schedule windows: the request is rejected with ALWAYS_ON_CONFLICT. The reverse also holds — a wake window cannot be added to an always-on server. 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 — immediate stop without waiting for the timer.
• Start server — wake from sleeping.
• Provider plans — the sleepPriceMonthly field shows the rate in sleep mode.
• Get server — check the current sleepAfterMinutes value.