## 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 rate is substantially lower). Works for any mode — both BLACKHOLE and OPEN. The server can be started again via [`POST /start`](./start.md), and a request to the subdomain wakes it under the [automatic wake conditions](./wake.md).

## 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 while you are not on its development team):

```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` | 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 | `SERVER_NOT_FOUND` | No server with this `id` — deleted, or belonging to another API key while you are not on its development team |
| 409 | `MANAGED_SERVER_LIFECYCLE` | The server belongs to an AI agent or a bot. Stopping it is managed from the agent or bot card, not with `/stop`. To put such a server to sleep, call [`/sleep-now`](./sleep-now.md) |
| 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. Replace the server: delete it and create a new one. `error.hint` names the endpoint of each step only if that step is available to this request, and for an unavailable step it gives the reason for the refusal and what to change |
| 422 | `VM_POINTER_LOST` | The record has no `externalId`, but the cloud review does see a machine under this server's cloud name: the link is lost while the machine itself is most likely running and billed. Do NOT delete the server and create a new one — that would leave the machine running with no record at all. The server is not moved to `error`; contact support to have the link restored |
| 422 | `VM_MISSING` | The server is a Galaxy app in `running` status. The container has no VM of its own, so there is nothing to stop. The app can be removed with [`DELETE /v1/infra/servers/:id`](/docs/infra/servers/delete) if deletion is available to this request, otherwise `error.message` gives the reason for the refusal and what to change. There is no need to recreate the app; the operations that do apply to it are on the [Galaxy app](/docs/infra/galaxy) page |
| 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 it is charged at a separate sleep rate — lower than the rate for a running server. The sleep price of each plan is shown by the `sleepPriceMonthly` field in [Provider plans](/docs/infra/providers/plans). That is the plan's reference price, while the rate actually charged comes from the platform service catalog and may differ from it. The value `stopped` does not appear in v1 responses.
- **`/stop` resets `preventWake`** — the automatic flag that blocks waking. After stopping, the server can be brought up again with [`/wake`](./wake.md), and a request to the subdomain wakes it under the conditions described there.
- **For BLACKHOLE there is an alternative — [`/sleep-now`](./sleep-now.md).** The result is functionally identical. `/sleep-now` is called by the "Sleep" button in the UI and is explicitly marked as BH-specific; `/stop` is universal for any mode.

## See also

- [Start the server](./start.md)
- [Sleep now](./sleep-now.md)
- [Configure auto-sleep](./sleep.md)
- [Delete a server](/docs/infra/servers/delete)