## Configure auto-sleep

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

Configures the stored automatic sleep timer of a BLACKHOLE server. If no inbound HTTP requests reach the application for the effective timeout, the server stops automatically. It can be brought back up by a [`/wake`](./wake.md) call, though a request to the HTTPS subdomain does not always wake the server — see that page for the conditions. Passing `null` stores the “Never” setting. How it interacts with [wake-schedule windows](/docs/infra/wake-schedules) is described below.

`null` disables idle auto-sleep. The `.com` plans are non-preemptible, so a dedicated machine with `null` outside the `SCHEDULE` run mode does not idle-sleep, even with previously stored windows. In the `SCHEDULE` run mode, the assigned work schedule determines sleep. Creating or updating wake windows normally requires an explicit numeric value (`15`, `30`, `60`, or `240`).

A server with `idleSleepProtected: true` must stay reachable, so a numeric threshold is refused with `400 AGENT_IDLE_SLEEP_FORBIDDEN`. This is an agent or bot server, or an ordinary application with an enabled fetch bot. `null` and the [scheduled run mode](./run-mode.md) remain available.

For a continuous 24/7 workload, store `null`: the `.com` plans are non-preemptible, and writing `null` also removes an assigned work schedule. 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. List: [`GET /v1/infra/servers`](/docs/infra/servers/list) |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `sleepAfterMinutes` | number \| null | **yes** | Stored idle timeout in minutes. Allowed values: `15`, `30`, `60`, `240`, or `null`. `null` means “Never”. Setting `null` while enabled wake windows exist is rejected as a settings conflict, unless the server is in the `SCHEDULE` run mode. 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) |
| `data.workScheduleCleared` | boolean | `true` when this write removed a work schedule that was assigned to the server |

## Response example

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

## Error response example

400 — attempting to enable guaranteed “Runs around the clock” mode (`null`) while wake-schedule windows are enabled, if the server is not in the `SCHEDULE` run mode:

```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 | `GALAXY_APP_USE_GALAXY_ROUTE` | The server is a Galaxy app. It sleeps together with its host, and its idle timer is not set through the Vibecode API. For what applies to an app, see the [Galaxy app](/docs/infra/galaxy) page |
| 400 | `BLACKHOLE_ONLY` | The server is in `OPEN` mode — auto-sleep is not available |
| 400 | `ALWAYS_ON_CONFLICT` | Attempting to set `null` while [wake-schedule windows](/docs/infra/wake-schedules) are enabled — delete or disable the windows first. A server in the `SCHEDULE` [run mode](/docs/infra/lifecycle/run-mode) does not get this code: its sleep is declared by the schedule |
| 400 | `AGENT_IDLE_SLEEP_FORBIDDEN` | The server has `idleSleepProtected: true`, so numeric `sleepAfterMinutes` is forbidden. This is an agent or bot server, or an ordinary application with an enabled fetch bot. `null` is accepted, and schedule-based savings remain available through the run mode |
| 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, but 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, was deleted, or is bound to another API key and you are not on its development team |
| 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.** Inbound HTTP requests that reach the application through the tunnel reset the timer. Actual activity is checked every few minutes through Gateway metrics, and the moment of the last request is exposed as `lastRequestAt` by [`GET /v1/infra/servers/:id/metrics`](/docs/infra/deploy/metrics). Outbound requests made by the application do not count as activity. The platform separately protects an application with an enabled fetch bot: it has `idleSleepProtected: true`, a numeric threshold is unavailable, and outbound polling does not have to imitate inbound traffic. For other applications, outbound polling does not keep the machine online.
- **Auto-wake is preserved.** A server put to sleep by the timer wakes on a call to [`/deploy`](/docs/infra/deploy/deploy)/[`/wake`](./wake.md)/[`/start`](./start.md), and a request to the HTTPS subdomain wakes it under the [automatic wake conditions](./wake.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).
- **Agent servers, managed-bot servers, and applications with an enabled fetch bot do not idle-sleep without a schedule.** Machines created by the platform for an AI agent or managed bot have `createdVia` set to `agent` or `bot`. An ordinary server or Galaxy application has the same protection while an enabled fetch bot is associated with it. In every case [`GET /v1/infra/servers/:id`](../servers/get.md) returns `idleSleepProtected: true`, and a numeric `sleepAfterMinutes` request is rejected with `400 AGENT_IDLE_SLEEP_FORBIDDEN`. An ordinary application's previously stored threshold is kept and takes effect again after its last fetch bot is disabled. A schedule remains available and outranks protection. A webhook bot alone does not enable protection.
- **`ALWAYS_ON_CONFLICT` protects only the “Runs around the clock” mode.** The rules are asymmetric: setting `sleepAfterMinutes: null` while [wake-schedule windows](/docs/infra/wake-schedules) are enabled is rejected, and creating or updating any window while `null` is stored is rejected even with `enabled: false`. The window-write gate excludes an app in a galaxy, which inherits the galaxy's plan, and a server in the `SCHEDULE` [run mode](/docs/infra/lifecycle/run-mode). When writing `null`, the exception applies to the `SCHEDULE` run mode. Deleting a window is allowed. Previously stored windows do not enable idle auto-sleep for a dedicated machine with `null` outside the `SCHEDULE` run mode. Before switching to “Never”, delete or disable the enabled windows, or keep a numeric timeout.
- **Writing the timeout clears an assigned work schedule.** A schedule outranks the timeout: while one is assigned the server runs during its windows, and the stored number would not affect its behavior at all. So the request means what it says — a number moves the server to "Sleeps when there are no requests", `null` to "Runs around the clock", and either one drops the schedule together with the wake windows it generated. `data.workScheduleCleared` tells you it happened. Windows created by hand are untouched. The server's current mode is shown in the `runMode` and `workSchedule` fields of [`GET /v1/infra/servers/:id`](/docs/infra/servers/get).
- **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)
- [Start the server](./start.md)
- [Server metrics](/docs/infra/deploy/metrics)
- [Provider plans](/docs/infra/providers/plans)
- [Get a server](/docs/infra/servers/get)