## 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](/docs/infra/providers/plans) for the available plans and their characteristics.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | ID of a server in BLACKHOLE mode |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `sleepAfterMinutes` | number \| null | **yes** | Idle timeout in minutes. Allowed values: `15`, `30`, `60`, `240`, or `null` (to disable auto-sleep). Other values are rejected with `VALIDATION_ERROR` |

## Examples

### curl — personal key

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

```bash
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

```javascript
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

```javascript
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

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.sleepAfterMinutes` | number \| null | The current timeout value (echo of what was passed) |

## Response example

```json
{
  "success": true,
  "data": {
    "sleepAfterMinutes": 60
  }
}
```

## Error response example

400 — invalid `sleepAfterMinutes` value:

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

400 — the server is not in BLACKHOLE:

```json
{
  "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:

```json
{
  "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

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | `sleepAfterMinutes` is not in the list `[15, 30, 60, 240, null]` |
| 400 | `BLACKHOLE_ONLY` | The server is in `OPEN` mode — auto-sleep is not available |
| 400 | `ALWAYS_ON_CONFLICT` | `null` while [wake-schedule windows](/docs/changelog) are enabled — delete or disable the windows first |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `NOT_FOUND` | The server does not exist, was deleted, or belongs to another API key |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/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`](/docs/infra/deploy/deploy)/[`/wake`](./wake.md)/[`/start`](./start.md).
- **The default value for new servers** is 60 minutes. The current value is returned by [`GET /v1/infra/servers/:id`](/docs/infra/servers/get).
- **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](/docs/changelog): 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`](./sleep-now.md).

## See also

- [Sleep now](./sleep-now.md) — immediate stop without waiting for the timer.
- [Start server](./start.md) — wake from `sleeping`.
- [Provider plans](/docs/infra/providers/plans) — the `sleepPriceMonthly` field shows the rate in sleep mode.
- [Get server](/docs/infra/servers/get) — check the current `sleepAfterMinutes` value.