## 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`](./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` |
| `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 due:

```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` | Server is in `OPEN` mode. For OPEN servers, use [`/stop`](./stop.md) |
| 400 | `NOT_RUNNING` | Server is not in `running` status (already sleeping, in error, or provisioning) |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `NOT_FOUND` | Server does not exist or belongs to another API key |
| 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.** 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`](/docs/infra/deploy/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](/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 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](./sleep.md) — `PATCH /v1/infra/servers/:id/sleep` — the server sleeps by itself after N minutes.
- [Stop the server](./stop.md) — universal stop (works for OPEN too).
- [Start the server](./start.md) — wake from `sleeping`.
- [Wake with waiting](./wake.md) — `POST /v1/infra/servers/:id/wake?wait=true` — blocking wake.