For AI agents: markdown of this page — /docs-content-en/infra/lifecycle/stop.md documentation index — /llms.txt

Stop the server

POST /v1/infra/servers/:id/stop

A graceful stop of a running server. The virtual machine is stopped at the provider, the status changes to sleeping, the open billing transaction for the active period is closed, and a transaction for the sleep period is opened (the sleep rate is substantially lower). Works for any mode — both BLACKHOLE and OPEN. The server can be started again via POST /start, and a request to the subdomain wakes it under the automatic wake conditions.

Parameters

Parameter In Type Required Description
id path string (UUID) yes Server ID

The request body is empty.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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/stop

JavaScript — personal key

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

JavaScript — OAuth application

javascript 
await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/stop`,
  {
    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 stop

Response example

JSON 
{ "success": true }

Error response example

422 — the server exists but is not in running status (e.g. sleeping). The response carries the current state and the actions available now:

JSON 
{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is SLEEPING; /stop requires RUNNING.",
    "userMessage": "Server is currently SLEEPING. Stop only applies to a RUNNING server.",
    "currentState": { "status": "sleeping", "blackholeStatus": "DISCONNECTED", "hasExternalId": true },
    "availableActions": ["wake", "start", "repair", "delete"]
  }
}

404 — no server with this id (deleted, or belonging to another API key while you are not on its development team):

JSON 
{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}

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
403 INFRA_FORBIDDEN_FOR_COWORK_KEY The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
403 SERVER_ROLE_FORBIDDEN You are on this server's development team with the Developer role, and this operation is open to the Administrator role. error.hint carries your role, the required threshold and the list of calls that are open to you. Role breakdown — List servers
404 SERVER_NOT_FOUND No server with this id — deleted, or belonging to another API key while you are not on its development team
422 SERVER_WRONG_STATE The server exists but is not in running status. error.currentState carries the current state; error.availableActions lists what you can do now
422 VM_MISSING The server record has no cloud VM: provisioning never finished or the VM was removed manually — delete the server and create a new one
422 VM_MISSING The server is a Galaxy app in running status. The container has no VM of its own, so there is nothing to stop: to remove the app, call DELETE /v1/infra/servers/:id. There is no need to recreate the app; the operations that do apply to it are on the Galaxy app page
429 RATE_LIMITED The platform-wide request limit was exceeded
502 PROVIDER_ERROR The cloud provider returned an error while stopping

Full list of common API errors — Errors.

Known specifics

  • Why sleeping, not stopped. This is Infrastructure API terminology: a stopped server is called "sleeping" because it is charged at a separate sleep rate — lower than the rate for a running server. The sleep price of each plan is shown by the sleepPriceMonthly field in Provider plans. That is the plan's reference price, while the rate actually charged comes from the platform service catalog and may differ from it. The value stopped does not appear in v1 responses.
  • /stop resets preventWake — the automatic flag that blocks waking. After stopping, the server can be brought up again with /wake, and a request to the subdomain wakes it under the conditions described there.
  • For BLACKHOLE there is an alternative — /sleep-now. The result is functionally identical. /sleep-now is called by the "Sleep" button in the UI and is explicitly marked as BH-specific; /stop is universal for any mode.

See also