## 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`](./sleep.md).

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

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

### curl — OAuth application

```bash
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](/docs/infra/wake-schedules) 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`](./stop.md) |
| 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](/docs/infra/galaxy) |
| 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` | The key is not recognized — no such key exists on the platform |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key) |
| 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](/docs/infra/servers/list) |
| 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](/docs/errors).

## Known specifics

- **On an OPEN server, use [`/stop`](./stop.md).** 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.** For a regular server, a manual `/sleep-now` does not set the wake block (`preventWake=true`): the server is brought up by [`/deploy`](/docs/infra/deploy/deploy) and [`/wake`](./wake.md) 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](/docs/infra/wake-schedules) 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

- [Configure auto-sleep](./sleep.md)
- [Stop the server](./stop.md)
- [Start the server](./start.md)
- [Wake the server](./wake.md)