Delete a server

DELETE /v1/infra/servers/:id

Deletes a server irreversibly: the virtual machine is destroyed at the provider, the database record is marked as DELETED, and open billing transactions are finalized. The AI agent that ran on the server is deleted together with it. A deleted server cannot be recovered — create a new one via POST /v1/infra/servers. Deletion is idempotent only for the virtual machine on the provider side: if it has already been deleted there, no error is returned. A repeated call for a server that is already marked deleted returns 404.

Parameters

Examples

curl — personal key

curl -X DELETE -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/db008c84-91a5-4e15-b9d5-6c6aa2838448

curl — OAuth application

curl -X DELETE -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success } = await res.json()
if (success) console.log('Server deleted')

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Response fields

The response is short — the body { "success": true } confirms the deletion. No additional data is returned.

Response example

{
  "success": true
}

Error response example

404 — the server is already deleted or does not exist:

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

Errors

The full list of common API errors — Errors.

Known specifics

• The AI agent that ran on the server is deleted together with it. The agent record is marked deleted, its bot is unregistered in Bitrix24, the agent key is revoked and requests made with it no longer pass, and the application card is removed from the Bitrix24 catalog. The agent cannot be reused after the server is deleted: create a new server and set up a new agent. For a Galaxy application the agent is removed after the slot has already been torn down, so the outcome of that step does not affect the response code — the response stays 200 { "success": true }.
• A 409 AGENT_DELETE_CONFLICT refusal means the server is still alive. Another request was changing the agent record at that moment — a concurrent delete or recovery of the same agent, for example — and the deletion did not go through. The server is not deleted, it keeps running and keeps being billed. The refusal is retryable: once the concurrent operation finishes, the same call goes through the normal path.
• Handling 404 on retries is normal. If the client lost the connection after the first DELETE, a retry will return 404. Catch 404 as "already deleted".
• If the virtual machine has already been deleted at the provider by another means (the provider's panel, manual cleanup), DELETE still succeeds and marks the database record as deleted.
• The quota is freed immediately. After deletion you can create a new server right away — MAX_SERVERS_REACHED will no longer count this record.
• Deletion works for any status. Servers in provisioning, running, sleeping, and error are all deleted normally.
• Source snapshots outlive the server. Saved code versions stay available after deletion: the list via GET /v1/infra/servers/:id/sources, the download via GET /v1/infra/servers/:id/sources/:versionId/download. The server itself is found with GET /v1/infra/servers and the includeDeleted=true parameter. How to remove versions you no longer need — Source code storage.
• A Galaxy application is deleted by this same method. If your Bitrix24 account hosts applications in galaxies (several applications run as containers on a shared host), DELETE /v1/infra/servers/:id removes the application the key owns: it tears down its container on the host and marks the record deleted. The response is 200 { "success": true }, the same as for a regular server.
• The platform wakes a sleeping Galaxy host on its own. If the host of a Galaxy application is asleep, the platform wakes it before tearing down the container — there is no need to wake another application and retry the request. The 502 GALAXY_HOST_UNREACHABLE error occurs only when the wake started and failed. In that case, retry the request a little later.
• A refused wake and a failed wake are different responses. If the platform is forbidden to start the host (frozen billing, expired access, a wake block), the request returns 409 GALAXY_HOST_WAKE_BLOCKED. This refusal is terminal: retrying is pointless until the cause is cleared. The cause arrives in error.reason — BILLING_FROZEN, ACCESS_EXPIRED, STOPPED or UNKNOWN. This response carries no error.hint: the hint describes recovering an unreachable host, and there is nothing to recover here.
• The 502 GALAXY_HOST_UNREACHABLE response has an error.hint field with a recovery plan. It is an object with four string fields: reason — why the host is unreachable right now, recovery — what to do, recoveryAction — the concrete call to retry, note — a caveat that the host status in the listing can lag behind the real tunnel state. The point of the hint: the server record is preserved until the container teardown actually runs on the host, so retrying the request in 1–2 minutes loses nothing. If this state persists for more than 15 minutes, the host is genuinely unreachable.
• A host that does not boot is the exception: the application is deleted without contacting it. Once the platform has proven that the host's guest operating system does not boot (the host record has provisionErrorCode equal to GUEST_NOT_BOOTING), the tunnel will never appear and waiting for it is pointless. In that case the request answers 200 — but only if the platform has also confirmed through the gateway that no live tunnel exists. That check is fail-safe: an unreachable gateway, an answer without a connection list, or a host that came back between the check and the deletion all keep the previous 502 even with the marker set. When every condition holds, the application record is closed and its access tokens, domain and catalog item are released. After deleting the applications one by one you delete the host itself with the regular call — the GALAXY_HAS_APPS refusal no longer appears. The marker is visible in advance in the provisionErrorCode field — GET /v1/infra/servers/:id.
• A Galaxy host with non-deleted applications is not deleted by this method. If the server is a Galaxy host that still has non-deleted applications, the request returns 409 GALAXY_HAS_APPS with an appCount field. Delete the applications one by one, then the host itself. If the applications cannot be deleted — for example, billing is frozen and the host cannot be started — delete the host together with its applications in your Vibecode account: the public API has no such operation.

See also

• Create a server
• List servers
• Get a server
• Stop a server
• Put a server to sleep
• Source code storage
• AI agents