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

cloudDelete values:

• confirmed — the cloud accepted the request to delete the machine.
• already-gone — the machine was already gone from the cloud.
• failed — the cloud did not accept the request. The server record is deleted and billing is stopped, but the machine may still be running. Do not treat the resource as destroyed. Retrying the request returns 404 — the server record no longer exists.
• not-applicable — the server has no virtual machine in the cloud, for example a Galaxy application.
• deferred — the server was still being created and no virtual machine was attached to it yet. This call sent no request to the cloud: if the machine gets created, the platform deletes it itself once creation reaches it. Billing is stopped; retrying answers 404.

For a client confirmed and already-gone are equivalent: the machine is deleted or being deleted. success is true for every cloudDelete value.

Response example

{
  "success": true,
  "cloudDelete": "confirmed"
}

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 from the Bitrix24 account, 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, "cloudDelete": "not-applicable" }.
• 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, "cloudDelete": "not-applicable" }.
• 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 means that wake or container teardown could not be confirmed. Restore host access before retrying.
• 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. A persistent failure requires checking both host access and container teardown; elapsed time alone does not prove that the host is gone.
• An unreachable host does not prove that an application is gone. The platform preserves the application and its binding until it confirms container and volume removal through the host. A guest boot error or a missing tunnel is insufficient. Restore host access, or delete the host together with its applications in your Vibecode account.
• 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