## Start the server

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

Brings a server up from the `sleeping`, `error`, or `provisioning` states. For `sleeping`, the virtual machine is started again at the provider and returns to `running` status as it becomes ready — the call returns a response immediately, without waiting for actual readiness; track it by polling [`GET /v1/infra/servers/:id`](/docs/infra/servers/get). For `error` with a connected tunnel (`blackholeStatus: "CONNECTED"`), the server is moved straight to `running` without contacting the provider. For `provisioning`, the start is retried without resetting the wait timer. If the server is not in one of these states — for example, already `running` — the call returns 422 `SERVER_WRONG_STATE` with the current state (`currentState`) and the list of available actions (`availableActions`).

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

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

### JavaScript — personal key

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/start`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
// Wait for readiness — poll GET /v1/infra/servers/:id
```

### JavaScript — OAuth application

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

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true`. The virtual machine has been started at the provider, or the start command has been dispatched in the background |

## Response example

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

## Error response example

422 — the server exists but is not in `sleeping`/`error`/`provisioning` status, for example already `running`. The response carries the current state and the actions available now:

```json
{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is RUNNING; /start requires one of SLEEPING, ERROR, PROVISIONING.",
    "userMessage": "Server is currently RUNNING. Start only applies to SLEEPING, ERROR, or PROVISIONING servers.",
    "currentState": { "status": "RUNNING", "blackholeStatus": "CONNECTED", "hasExternalId": true },
    "availableActions": ["reboot", "sleep-now", "delete"]
  }
}
```

## 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 |
| 402 | `ACCOUNT_FROZEN` | Vibecode balance is frozen. Top up and retry |
| 404 | `SERVER_NOT_FOUND` | No server with this `id` — deleted, or belonging to another API key |
| 409 | `CONFLICT` | The server status changed during the operation — retry the request |
| 422 | `SERVER_WRONG_STATE` | The server exists but is not in `sleeping`/`error`/`provisioning` status. `error.currentState` carries the current state; `error.availableActions` lists what you can do now |
| 422 | `VM_MISSING` | The record has no `externalId` — the virtual machine was not created or was deleted externally. 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 starting the virtual machine |

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

## Known specifics

- **Blocking variant.** If the client needs the server fully ready before the next step — use [`POST /wake?wait=true`](./wake.md) instead of `/start`. It waits for `status: "running"` + `blackholeStatus: "CONNECTED"` for up to ~6.5 minutes.
- **Manual `/start` bypasses `preventWake`.** Unlike automatic wake on subdomain access, an explicit `POST /start` clears the `preventWake` flag and starts the server even if it was blocked. Billing locks (`ACCOUNT_FROZEN`) are cleared by a separate top-up, not via `/start`.
- **For `running` it returns 422 `SERVER_WRONG_STATE`.** The server is already running — no repeat start is needed. For a reboot — [`POST /reboot`](./reboot.md).

## See also

- [Stop the server](./stop.md) — `POST /v1/infra/servers/:id/stop`.
- [Wake the server (with `?wait=true`)](./wake.md) — blocking variant that waits for readiness.
- [Sleep now](./sleep-now.md) — the reverse operation.
- [Refresh status](./refresh.md) — force a provider poll after start.
- [Get the server](/docs/infra/servers/get) — poll for readiness.