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

• 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.
• A Galaxy application is deleted by this same method. When a Bitrix24 account places 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 error 502 GALAXY_HOST_UNREACHABLE remains only when the host is unreachable or could not be woken, for example when it is frozen for billing. In that case retry the request shortly.
• The 502 GALAXY_HOST_UNREACHABLE response has an error.hint field with a recovery plan. It is an object of four strings: 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 the condition holds beyond 15 minutes, the host is genuinely down.
• 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 host's applications first, then the host itself.

#See also

• Create a server — POST /v1/infra/servers.
• List servers — GET /v1/infra/servers (deleted ones are not included in the output).
• Get a server — GET /v1/infra/servers/:id.
• Stop a server — an alternative to deletion, if you want to return to the server later.
• Put a server to sleep — to save money on a temporarily unused BLACKHOLE server.

#Create a server

POST /v1/infra/servers

Creates an application with a cloud provider. Always in Black Hole mode — iptables blocks all inbound ports, the application is invisible from the internet.

Your Bitrix24 account has two placement models, and what to expect after creation depends on the model:

• A dedicated virtual machine (the default model). The response is returned immediately with the provisioning status. Provisioning takes 1–3 minutes, after which you need to poll GET /v1/infra/servers/:id until status: "running" and blackholeStatus: "CONNECTED". The response contains the SSH data ssh.password and ssh.privateKey only once — they will be needed when switching to OPEN mode, so save them right away. This page describes that model in the request fields, response fields, and error table below.
• A Galaxy application — a container on a shared host. If your Bitrix24 account places apps in galaxies, the same POST /v1/infra/servers creates a Galaxy application instead of a virtual machine. In the response, this model is marked by createdVia: "galaxy". The "Galaxy application" section below describes the two startup scenarios, and the full model is on the Galaxy app page.

#Galaxy application

If your Bitrix24 account places apps in galaxies, POST /v1/infra/servers creates a Galaxy application — a container on a shared host rather than a dedicated virtual machine. The request and the call order are the same, but the lifecycle differs. In the response, this model is marked by createdVia: "galaxy". The full model, cost, and deploy differences are on the Galaxy app page.

Do not wait for CONNECTED before uploading the code. A Galaxy application never reaches blackholeStatus: "CONNECTED" on its own — its container is built on code upload. If you just poll the status, the app stays in provisioning, and after about 20 minutes the platform marks it as error and records in the provisionError field that the code was never uploaded. So upload the code right away — using one of the two scenarios below.

#Scenario 1 — transparent, recommended

A single request. Pass the application code in the source field of POST /v1/infra/servers together with runtime and start (and, if needed, install, env, port). The build runs in the background. After the response, poll GET /v1/infra/servers/:id until status: "running". A separate code-upload call is not needed.

curl -X POST https://vibecode.bitrix24.com/v1/infra/servers \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-crm-app",
    "displayName": "My CRM bot",
    "source": { "content": "<base64-archive>" },
    "runtime": "node20",
    "start": "node index.js",
    "install": "npm ci",
    "port": 3000
  }'

The source, runtime, start, install, env, port fields have the same meaning as in the POST /:id/deploy body:

Without the runtime and start fields, the source field returns 400 — both fields are required. On a Bitrix24 account without Galaxy mode, source is forbidden and returns 400 SOURCE_AT_CREATE_GALAXY_ONLY.

#Scenario 2 — two-step

Create the application without source — the response comes with the provisioning status and the hint next: "deploy". Immediately call POST /v1/infra/servers/:id/deploy with the code in source, the runtime, and the start command. Upload the code right away, without waiting for CONNECTED.

# Step 1 — create the application without code
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "bitrix-cloud", "name": "my-crm-app", "plan": "bc-medium", "region": "bc-eu-central" }'

# The response contains data.id, data.next = "deploy", and data.hint.
# Step 2 — upload the code right away, without waiting for CONNECTED
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "content": "<base64-archive>" },
    "runtime": "node20",
    "start": "node index.js",
    "port": 3000
  }'

provider, plan and region are required by the schema for a create without source; for a galaxy app the values are informational — the app inherits its host's plan and region.

#Diagnostics and environment variables

• The provisionError field. If the build or the startup failed, GET /v1/infra/servers/:id returns the failure reason in data.provisionError, and on an image-build failure — also the tail of the Docker build log. Read this field to find the cause.
• env variables are injected at start. Values from env are passed into the container at start time via docker run --env, not baked into the image. So API keys and secrets from env do not end up in the image layers.

#Request fields (body)

Note: for the dedicated-virtual-machine model the runtime parameter is not accepted in POST /v1/infra/servers — passing it will return 400 RUNTIME_PARAM_REMOVED. The runtime is installed at the deploy stage. See POST /:id/deploy. Exception — Galaxy mode: when source is passed, runtime is required (see the "Galaxy application" section), and 400 RUNTIME_PARAM_REMOVED is not returned in that case.

#Examples

#curl — personal key

# name — lowercase Latin letters, digits and hyphens only, first character a letter (^[a-z][a-z0-9-]*$)
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bitrix-cloud",
    "name": "my-crm-app",
    "displayName": "My CRM bot",
    "plan": "bc-small",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts"
  }'

#curl — OAuth application

# name — lowercase Latin letters, digits and hyphens only, first character a letter (^[a-z][a-z0-9-]*$)
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bitrix-cloud",
    "name": "my-crm-app",
    "displayName": "My CRM bot",
    "plan": "bc-small",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts"
  }'

#JavaScript — personal key

// name — lowercase Latin letters, digits and hyphens only, first character a letter (^[a-z][a-z0-9-]*$)
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'bitrix-cloud',
    name: 'my-crm-app',
    displayName: 'My CRM bot',
    plan: 'bc-small',
    region: 'bc-eu-central',
    image: 'ubuntu-2404-lts',
  }),
})
const { data } = await res.json()
console.log('Server ID:', data.id, 'Subdomain:', data.subdomain)

// Save the SSH credentials just in case — they are returned only once
if (data.ssh.privateKey) {
  await saveLocally(`${data.id}.key`, data.ssh.privateKey)
}

#JavaScript — OAuth application

// name — lowercase Latin letters, digits and hyphens only, first character a letter (^[a-z][a-z0-9-]*$)
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'bitrix-cloud',
    name: 'my-crm-app',
    displayName: 'My CRM bot',
    plan: 'bc-small',
    region: 'bc-eu-central',
    image: 'ubuntu-2404-lts',
  }),
})

#Response fields

#Response example

A dedicated virtual machine:

{
  "success": true,
  "data": {
    "id": "db008c84-91a5-4e15-b9d5-6c6aa2838448",
    "status": "provisioning",
    "provider": "bitrix-cloud",
    "name": "docs-test-temp",
    "kind": "STANDALONE",
    "ip": null,
    "ssh": {
      "user": "root",
      "port": 22,
      "password": "0FPIIR9EfO2OAeSSMK6bKA",
      "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAABG5vbmU…\n-----END OPENSSH PRIVATE KEY-----\n"
    },
    "plan": "bc-small",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts",
    "mode": "BLACKHOLE",
    "createdVia": "api",
    "subdomain": "app-92fb1c34",
    "blackholeStatus": "NONE",
    "accessPolicy": "OWNER_ONLY",
    "runtimeId": null,
    "runtimeStatus": null,
    "appUrl": "https://app-92fb1c34.vibecode.bitrix24.com",
    "createdAt": "2026-04-22T10:50:11.477Z"
  }
}

A Galaxy application via scenario 1 — source was passed, the build runs in the background. There are no ssh or next fields:

{
  "success": true,
  "data": {
    "id": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
    "status": "provisioning",
    "provider": "bitrix-cloud",
    "name": "my-crm-app",
    "kind": "GALAXY_APP",
    "galaxyId": "<galaxy-host-id>",
    "displayName": "My CRM bot",
    "ip": null,
    "ssh": null,
    "plan": "bc-medium",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts",
    "mode": "BLACKHOLE",
    "createdVia": "galaxy",
    "subdomain": "app-7c2b1f08",
    "blackholeStatus": "NONE",
    "accessPolicy": "OWNER_ONLY",
    "runtimeId": null,
    "runtimeStatus": null,
    "appUrl": "https://app-7c2b1f08.vibecode.bitrix24.com",
    "createdAt": "2026-04-22T10:50:11.477Z"
  }
}

A Galaxy application via scenario 2 — source was not passed, next and hint appear:

{
  "success": true,
  "data": {
    "id": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
    "status": "provisioning",
    "provider": "bitrix-cloud",
    "name": "my-crm-app",
    "kind": "GALAXY_APP",
    "galaxyId": "<galaxy-host-id>",
    "displayName": "My CRM bot",
    "ip": null,
    "ssh": null,
    "plan": "bc-medium",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts",
    "mode": "BLACKHOLE",
    "createdVia": "galaxy",
    "subdomain": "app-7c2b1f08",
    "blackholeStatus": "NONE",
    "accessPolicy": "OWNER_ONLY",
    "runtimeId": null,
    "runtimeStatus": null,
    "appUrl": "https://app-7c2b1f08.vibecode.bitrix24.com",
    "createdAt": "2026-04-22T10:50:11.477Z",
    "next": "deploy",
    "hint": "This is a galaxy app — POST /v1/infra/servers/:id/deploy with source.content now; it will not reach \"running\" on its own."
  }
}

If a Galaxy application's build failed, GET /v1/infra/servers/:id returns the reason in data.provisionError:

{
  "success": true,
  "data": {
    "id": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
    "status": "error",
    "createdVia": "galaxy",
    "provisionError": "Docker build failed: npm ci exited with code 1"
  }
}

#Error response example

400 — validation failed (the name starts with an uppercase letter):

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "name: Name must start with a letter and contain only lowercase letters, digits, and hyphens"
  }
}

#Errors

The full list of common API errors — Errors.

#The `error.hint` object

On a Bitrix24 account that places applications in a galaxy, the INVALID_REQUEST and RUNTIME_PARAM_REMOVED errors are extended with an error.hint object. It names the reason for the refusal and gives a ready-made request body. The condition differs between the two codes. For INVALID_REQUEST the hint arrives when the body carries neither source nor the full provider + plan + region tuple. For RUNTIME_PARAM_REMOVED it arrives when runtime is passed without source, even if the tuple is filled in completely. On a Bitrix24 account with dedicated virtual machines there is no hint in either case.

Do not confuse it with data.hint from a successful response: that one is a string about the next step after creating an application via scenario 2, this one is an object inside error.

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "provider: Required; plan: Required; region: Required",
    "hint": {
      "reason": "This portal places new apps on shared galaxy hosts, and the request lacked `source` and the full provider/plan/region tuple.",
      "recovery": "RECOMMENDED: create-and-deploy in ONE call — POST /v1/infra/servers { name, source: { content }, runtime, start }; OMIT provider/plan/region. Two-step also works: pass provider/plan/region (informational for a galaxy — values from GET /v1/infra/providers catalogs) to create an empty slot, then POST /v1/infra/servers/:id/deploy with the source. See GET /v1/me -> deployment.galaxyApp.checklist. For a deliberate dedicated standalone VM pass placement: \"dedicated\" together with provider/plan/region.",
      "example": {
        "name": "<slug>",
        "source": { "content": "<base64 gzip-tar of the app>" },
        "runtime": "node20",
        "start": "node server.js",
        "port": 3000
      }
    }
  }
}

If the body carries placement: "dedicated", the hint is different: it suggests adding provider, plan and region while keeping the dedicated server, instead of moving the application into a galaxy container.

#Idempotency

Pass the optional Idempotency-Key header to safely retry creating a standalone server. If the response to the first request is lost (a network drop, a load-balancer timeout), a retry with the same key does not create a second server — it returns the same server the first request created, with status 201 and an Idempotent-Replayed: true response header.

• The key is a 1–255 character string from [A-Za-z0-9_.:-]. It is scoped to your API key.
• On a replay the one-time SSH credentials are not re-exposed. In the response body ssh.privateKey and ssh.password are null, and a note field explains this. Keep the credentials from the first create response.
• The header applies to standalone servers only. On galaxy-placement Bitrix24 accounts a well-formed key is ignored without an error, and the retry protection does not extend to that path.
• The header is not supported together with graduateFrom for a dedicated server — it returns 400 IDEMPOTENCY_UNSUPPORTED_WITH_GRADUATION.

#Known specifics

• Examples of valid and invalid names by the pattern ^[a-z][a-z0-9-]*$:
  • Valid: my-app, bot-1, crm-dashboard.
  • Invalid: My-App (uppercase), bot_1 (underscore), my.app (dot), café (non-ASCII letters).
• sshPublicKey vs auto-generation. If you pass your own public key — the platform does not generate a private one, and ssh.privateKey in the response will be null. The password in ssh.password is still returned.
• When region in the response differs from the requested one. The requested zone may have run out of IP addresses (Address space exhausted) — then the platform automatically tries the next zones in the order from GET /v1/infra/providers/:providerId/regions, and records this in the audit log with the SERVER_ZONE_FALLBACK event.
• Provisioning timeout is 15 minutes. If status stays in provisioning longer, the platform moves the server to error and fills in provisionError and provisionErrorCode. After that, all that remains is to call DELETE and create a new one.
• The runtime is installed at the deploy stage. The runtime parameter has been removed from POST /v1/infra/servers (it will return 400 RUNTIME_PARAM_REMOVED). Specify runtime in the body of POST /:id/deploy — it will be installed between archive extraction and application start.

#See also

• Providers and catalogs
• Get a server
• List servers
• Update name and description
• Delete a server
• Deploy API
• Full application deploy
• List of runtimes
• Plan and access
• Access mode