For AI agents: markdown of this page — /docs-content-en/infra/lifecycle/sleep-now.md documentation index — /llms.txt

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 rate is lower). Useful for one-off savings when you know the server won't be needed for the next few hours. To stop the server automatically after N minutes of inactivity, use PATCH /sleep.

Parameters

Parameter In Type Required Description
id path string (UUID) yes ID of a server in BLACKHOLE mode, status running

The request body is empty.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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

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

JavaScript — OAuth application

javascript 
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

Field Type Description
success boolean true both when the server was put to sleep and when sleep was deferred
data object Present only when sleep was deferred. On a successful transition to sleeping, the response carries no data block
data.slept boolean Always false — the server stayed in running status
data.reason string Why sleep was declined. The only value is WAKE_IMMINENT

Response example

The server was moved to sleeping:

JSON 
{ "success": true }

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

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

Error response example

400 — server not in BLACKHOLE:

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

Errors

HTTP Code Description
400 BLACKHOLE_ONLY The server is in OPEN mode. For OPEN servers, use /stop
400 GALAXY_APP_USE_GALAXY_ROUTE The server is a Galaxy app. It sleeps together with its host. This code is returned regardless of the app status, and NOT_RUNNING is not returned instead — see Galaxy app
400 NOT_RUNNING The server is not in running status (already sleeping, in an error state, or still provisioning)
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired API key
403 INFRA_FORBIDDEN_FOR_COWORK_KEY The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
403 SERVER_ROLE_FORBIDDEN You are on this server's development team with the Developer role, and this operation is open to the Administrator role. error.hint carries your role, the required threshold and the list of calls that are open to you. Role breakdown — List servers
404 NOT_FOUND The server does not exist or belongs to another API key while you are not on its development team
409 CONFLICT State race — the server status changed during the operation
429 RATE_LIMITED The platform-wide request limit was exceeded

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 sets no block: the server is brought up by /deploy and /wake calls, and a request to its HTTPS subdomain wakes it under the conditions described on those pages.
  • 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 /start on the matching card can wake it. Regular 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 canceled so the machine is not shut down right before it has to be brought back up. The response arrives with status 200 and the fields slept: false, reason: "WAKE_IMMINENT" — the server stayed in running status. Repeat the call once the window has passed. 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