## Wake server

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

Wakes a server from `sleeping` or `provisioning`. Unlike [`/start`](./start.md), `/wake` supports a blocking mode via `?wait=true` — the response is returned only when the server is fully ready (the virtual machine has started **and** the tunnel has connected) or the timeout fires. Use the blocking mode when the client needs readiness before the next step (a cron job, a triggered call), and the asynchronous one when you can afford to poll.

## Parameters

| Parameter | In | Type | Required | Default | Description |
|----------|---|-----|:-----:|-----------|----------|
| `id` | path | string (UUID) | yes | — | ID of a server in `sleeping` or `provisioning` status |
| `wait` | query | string | no | — | `true` — blocking mode: the response returns only when the server is ready (up to 6.5 minutes) or the timeout fires. Any other value — asynchronous mode, the response returns immediately |

The request body is empty.

## Examples

### curl — personal key

```bash
# Asynchronous call — response immediately, check readiness by polling
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/wake

# Blocking — waits for readiness up to ~6.5 minutes
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/wake?wait=true"
```

### 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/wake?wait=true"
```

### JavaScript — personal key

```javascript
// Blocking variant — simplest for subsequent steps
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/wake?wait=true`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (!body.success) {
  // Rich error: show the user userMessage, suggest alternatives
  console.error(body.error.userMessage ?? body.error.message)
  if (body.error.alternatives) console.log('Options:', body.error.alternatives)
  throw new Error(body.error.code)
}
console.log(`Server ready: ${body.data.appUrl}`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/wake?wait=true`,
  {
    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 wake |
| `data.id` | string (UUID) | Server ID |
| `data.status` | string | Current status (`RUNNING` on success with `wait=true`; `PROVISIONING` in asynchronous mode) |
| `data.blackholeStatus` | string | Tunnel state (`CONNECTED` in blocking mode on success) |
| `data.appUrl` | string \| null | HTTPS address of the application |

## Response example

Successful wake (`?wait=true`):

```json
{
  "success": true,
  "data": {
    "id": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "status": "RUNNING",
    "blackholeStatus": "CONNECTED",
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.com"
  }
}
```

## Error response example

402 — a commercial plan is required (rich error for AI agents):

```json
{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Waking this server requires a commercial Bitrix24 plan or an active trial",
    "userMessage": "Waking the server requires a commercial Bitrix24 plan or an active trial. Get a plan at https://www.bitrix24.com/prices/",
    "alternatives": [
      "Upgrade the Bitrix24 plan and retry",
      "Switch to AI Router with BYOK keys — it works on any plan"
    ],
    "hint": "Do not retry automatically — a user action is required"
  }
}
```

## 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 | `COMMERCIAL_PLAN_REQUIRED` | The plan is free and the trial is unavailable — upgrade your Bitrix24 plan |
| 402 | `INT_TARIFF_REQUIRED` | The Bitrix24 plan is free — waking requires a commercial plan (a demo plan grants a limited trial) |
| 402 | `TRIAL_EXPIRED` | The trial was used and has ended |
| 402 | `BILLING_EXHAUSTED` | The Vibecode balance is exhausted — top it up |
| 402 | `ACCOUNT_FROZEN` | The balance is frozen |
| 403 | `SERVER_WAKE_BLOCKED` | Wake blocked for a non-billing reason (an ended trial, an administrative block, security violations) |
| 404 | `NOT_FOUND` | The server is not in `sleeping`/`provisioning` status, was deleted, or belongs to another API key |
| 422 | `VM_MISSING` | The record has no `externalId` — the virtual machine was not created on the provider side. Delete the server and create a new one |
| 429 | `RATE_LIMITED` | The request rate limit was exceeded. The response carries a `Retry-After` header with the recommended pause |
| 502 | `PROVIDER_ERROR` | The cloud provider returned an error while starting the virtual machine |
| 503 | `WAKE_TIMEOUT` | The blocking `?wait=true` call timed out (~6.5 minutes) before the server became ready. The server returns to `sleeping` — try again |

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

## Known specifics

- **Behavior on a `?wait=true` timeout.** If the virtual machine has not come up within ~6.5 minutes, the endpoint returns `503 WAKE_TIMEOUT` and tries to roll the server back to `sleeping` — so the quota is not left hanging on a "forever stuck" server. Retry `/wake` or call [`/repair`](./repair.md).
- **Rich-error fields for AI agents.** On 402/403 the error body additionally contains `userMessage` (a localized message for the user), `alternatives` (a list of resolution paths), and `hint` (advice to the AI agent on whether to retry automatically or not). Use these fields in the UI instead of the bare `code`/`message`.
- **`/wake` is not needed when accessing through the HTTPS subdomain.** Any request to the server's HTTPS subdomain automatically wakes the Black Hole server. An explicit `/wake` is needed when:
  - The client needs a programmatic "wake first, then act" gate — via `wait=true`.
  - The server is marked `preventWake=true` (a billing block that requires manual action).
- **Check availability BEFORE the call.** Before calling `/wake`, call [`GET /v1/me`](/docs/keys-auth) and look at `capabilities.servers.wake.available`. If it is `false`, the user must take action (top up the balance, upgrade the plan) before waking becomes possible.
- **`/wake` is not suitable for an `error` server** — use [`/start`](./start.md) or [`/repair`](./repair.md).

## See also

- [Start server](./start.md) — `POST /v1/infra/servers/:id/start` — a manual start without blocking.
- [Sleep now](./sleep-now.md) — the inverse operation.
- [Repair tunnel](./repair.md) — if the server woke up but the tunnel does not connect.
- [Plan and access](/docs/infra#plan-and-access) — context for 402 errors.