## Stop the server

`POST /v1/infra/servers/:id/stop`

A graceful stop of a running server. The virtual machine is stopped at the provider, the status changes to `sleeping`, the open billing transaction for the active period is closed, and a transaction for the sleep period is opened (the sleep tariff is substantially lower). Works for any mode — both BLACKHOLE and OPEN. The server can be started again via [`POST /start`](./start.md) or woken automatically by accessing the subdomain.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | Server ID |

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/stop
```

### 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/stop
```

### JavaScript — personal key

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

### JavaScript — OAuth application

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/stop`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful stop |

## Response example

```json
{ "success": true }
```

## Error response example

422 — the server exists but is not in `running` status (e.g. `sleeping`). The response carries the current state and the actions available now:

```json
{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is SLEEPING; /stop requires RUNNING.",
    "userMessage": "Server is currently SLEEPING. Stop only applies to a RUNNING server.",
    "currentState": { "status": "SLEEPING", "blackholeStatus": "DISCONNECTED", "hasExternalId": true },
    "availableActions": ["wake", "start", "repair", "delete"]
  }
}
```

404 — no server with this `id` (deleted, or belonging to another API key):

```json
{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `SERVER_NOT_FOUND` | No server with this `id` — deleted, or belonging to another API key |
| 422 | `SERVER_WRONG_STATE` | The server exists but is not in `running` status. `error.currentState` carries the current state; `error.availableActions` lists what you can do now |
| 422 | `VM_MISSING` | The server record has no cloud VM (provisioning never finished or the VM was removed manually) — delete the server and create a new one |
| 429 | `RATE_LIMITED` | The platform-wide request limit was exceeded |
| 502 | `PROVIDER_ERROR` | The cloud provider returned an error while stopping |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **Why `sleeping`, not `stopped`.** This is Infrastructure API terminology: a stopped server is called "sleeping" because billing for it follows a separate `sleepPriceMonthly` tariff (see [provider tariffs](/docs/infra/providers/plans)) — lower than the active one. The value `stopped` does not appear in v1 responses.
- **`/stop` resets `preventWake`** (the automatic flag that blocks waking) — after stopping, the server can again be woken automatically by accessing the subdomain or via [`/wake`](./wake.md).
- **For BLACKHOLE there is an alternative — [`/sleep-now`](./sleep-now.md).** The result is functionally identical. `/sleep-now` is used from the "Sleep" UI button and is explicitly marked as BH-specific; `/stop` is universal for any mode.

## See also

- [Start the server](./start.md) — `POST /v1/infra/servers/:id/start`.
- [Sleep now](./sleep-now.md) — a synonym for BLACKHOLE.
- [Configure auto-sleep](./sleep.md) — so the server sleeps by itself after N minutes of inactivity.
- [Delete the server](/docs/infra/servers/delete) — full deletion of the virtual machine.