#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. 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 — 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

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

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. 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.
• /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 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 or /repair.

#See also

• Start server — POST /v1/infra/servers/:id/start — a manual start without blocking.
• Sleep now — the inverse operation.
• Repair tunnel — if the server woke up but the tunnel does not connect.
• Plan and access — context for 402 errors.

#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. 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

The request body is empty.

#Examples

#curl — personal key

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/start

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

#JavaScript — personal key

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

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

#Response example

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

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

Full list of common API errors — Errors.

#Known specifics

• Blocking variant. If the client needs the server fully ready before the next step — use POST /wake?wait=true 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.

#See also

• Stop the server — POST /v1/infra/servers/:id/stop.
• Wake the server (with ?wait=true) — blocking variant that waits for readiness.
• Sleep now — the reverse operation.
• Refresh status — force a provider poll after start.
• Get the server — poll for readiness.