Wake server

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

Wakes a server from sleeping or provisioning. Unlike /start, /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. While waiting, the platform re-checks the machine state with the cloud and re-issues the start command if it never landed; a connected tunnel counts as proof of readiness even when the server status has not refreshed yet. 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

The request body is empty.

Examples

curl — personal key

# Asynchronous call — responds 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

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

// 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 userMessage to the user, offer 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

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

Response example

Successful wake (?wait=true):

{
  "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):

{
  "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

The full list of common API errors — 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. Inside that window the platform re-issues the start command whenever the cloud loses it, so a timeout means the machine genuinely did not come up, not that the command went missing. Retry /wake or call /repair.
• 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.
• A request to the subdomain does not always wake the server. A wake is triggered in four cases: the server has access policy PUBLIC, the visitor is authenticated, the request carries an access token in api-bearer mode, or the recipient opens a share-url link. A server with a wake block does not come up in these cases either — see the item below. An unauthenticated request to a server with any other policy, including the default OWNER_ONLY, leaves the server in sleeping status: a regular request gets the sign-in page with status 200, and an API client — that is, a request carrying Accept: application/json, Authorization: Bearer, or X-Requested-With: XMLHttpRequest, as well as any request under the /api/ path — gets 401 BH_LOGIN_REQUIRED. On a server with policy PUBLIC, GET and HEAD requests from search crawlers and automated clients — for example curl, wget, python-requests, go-http-client, java/, headless browsers, and a request with no User-Agent header — do not bring the machine up, so that crawling does not keep it running. On such a server POST, PUT, PATCH, and DELETE requests wake it from any client: those are webhook and API calls, not crawling. From a script or a console, bring the server up with an explicit /wake and wait=true — then the response arrives once the server is already accepting requests.
• A server with the preventWake flag is not brought up by /wake — the refusal codes are in the table above. The platform sets this flag when the balance is frozen, the trial period ends, or an administrative block is applied, and a server that belongs to an agent or a bot gets it on any stop — from its card or through /sleep-now. A standalone server is brought up by /start: it clears the block, but does not bypass a frozen balance. For a Galaxy app, a block on the host blocks /start as well — see Galaxy app.
• Check availability BEFORE the call. Before calling /wake, call GET /v1/me 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.
• The machine's public address is different after a wake. A woken machine receives a new address, so the ip field in GET /v1/infra/servers/:id returns a different value after every sleep cycle. This applies to all plans. Whatever reaches the server by its address — a DNS record, external monitoring — should point at the HTTPS subdomain in the appUrl field instead: a wake does not change it. The opposite direction has no such fix: when an external service admits only an allowlist of IPs, there is nothing to put on that list — the platform provides no permanent outbound address in any placement model, see Outbound IP.
• /wake is not suitable for an error server — use /start or /repair.

Galaxy apps (`kind=GALAXY_APP`)

On a Galaxy app, ?wait=true does not wait for readiness: the response arrives immediately, and the WAKE_TIMEOUT code never occurs here. After a cold host boot the app stays in sleeping status for a while — track readiness by polling GET /v1/infra/servers/:id.

The full map of an app's lifecycle operations is on the Galaxy app page.

See also

• Start the server
• Sleep now
• Repair tunnel
• Plan and access