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 — the balance is frozen, and the server will not come up until the balance is topped up (rich error for AI agents):

{
  "success": false,
  "error": {
    "code": "BILLING_EXHAUSTED",
    "message": "Balance depleted — top up to resume",
    "userMessage": "Your Vibecode balance is empty. Top up to resume your servers.",
    "alternatives": [
      { "type": "topup", "description": "Top up your balance in the billing section" }
    ],
    "hint": "Ask the user to top up their VibeCode balance. After top-up the server can be woken normally."
  }
}

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 and gets an authentication refusal. Both representations use HTTP 401: browser navigation gets the HTML sign-in page, while a machine-shaped request gets JSON BH_LOGIN_REQUIRED. JSON is selected by Accept: application/json, Content-Type: application/json, Authorization: Bearer, X-Api-Key, X-Requested-With: XMLHttpRequest, a /v1/… or /api/… path, or any non-navigation Sec-Fetch-Dest value (including empty); a request with neither explicit HTML nor a destination also defaults to JSON. These signals take precedence over explicit HTML and Sec-Fetch-Dest: document|iframe|frame. A bare POST with Accept: */* therefore gets JSON 401. 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 flag is set when the balance is frozen, platform access 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, waking is unavailable right now: the balance is frozen or the key is restricted, and the reason field names the cause. The flag accounts for neither the plan nor the server's own wake block, so 403 SERVER_WAKE_BLOCKED is possible even when it is true.
• 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