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
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionServer 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
Fieldsuccess Typeboolean Descriptiontrue 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
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe 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
HTTP403 CodeSERVER_ROLE_FORBIDDEN DescriptionYou 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
HTTP404 CodeSERVER_NOT_FOUND DescriptionNo server with this id — deleted, or belonging to another API key while you are not on its development team
HTTP409 CodeMANAGED_SERVER_LIFECYCLE DescriptionThe server belongs to an AI agent or a bot. Stopping it is managed from the agent or bot card, not with /stop. To put such a server to sleep, call /sleep-now
HTTP422 CodeSERVER_WRONG_STATE DescriptionThe server exists but is not in running status. error.currentState carries the current state; error.availableActions lists what you can do now
HTTP422 CodeVM_MISSING DescriptionThe server record has no cloud VM: provisioning never finished or the VM was removed manually. Replace the server: delete it and create a new one. error.hint names the endpoint of each step only if that step is available to this request, and for an unavailable step it gives the reason for the refusal and what to change
HTTP422 CodeVM_POINTER_LOST DescriptionThe record has no externalId, but the cloud review does see a machine under this server's cloud name: the link is lost while the machine itself is most likely running and billed. Do NOT delete the server and create a new one — that would leave the machine running with no record at all. The server is not moved to error; contact support to have the link restored
HTTP422 CodeVM_MISSING DescriptionThe server is a Galaxy app in running status. The container has no VM of its own, so there is nothing to stop. The app can be removed with DELETE /v1/infra/servers/:id if deletion is available to this request, otherwise error.message gives the reason for the refusal and what to change. There is no need to recreate the app; the operations that do apply to it are on the Galaxy app page
HTTP429 CodeRATE_LIMITED DescriptionThe platform-wide request limit was exceeded
HTTP502 CodePROVIDER_ERROR DescriptionThe 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