Servers

CRUD operations for servers: create a new server, list your servers, fetch details of a single server by ID, update its name and description, and delete a server. A created server is always in Black Hole mode — invisible from the internet, with access to the application only via an HTTPS subdomain.

Scope: vibe:infra

Create a server

POST /v1/infra/servers

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

There are two placement models, and what to expect after creation depends on the one your Bitrix24 account uses:

• 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 credentials 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 when you upload the code. 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, healthPath fields have the same meaning as in the POST /:id/deploy body:

The one-shot create accepts no other deploy fields: preStart, systemd, serviceName, cleanDeploy, extractTo, hardening, preserveEnv, dataDirs, dataDirsRecursive return 400 UNKNOWN_PARAM, and the full list of accepted fields arrives in details.validParams. These fields belong to a dedicated virtual machine deploy and do not apply to a Galaxy application — put the commands that must run before the application starts into install.

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

During the trial period, first read the deployment and capabilities.servers.create blocks from GET /v1/me. When galaxyApp is present, a one-shot create is worth trying, but the block reflects stored state and does not guarantee success: only the POST checks live capacity. When Galaxy mode is disabled, placementNote is absent and a request carrying source returns 400 SOURCE_AT_CREATE_GALAXY_ONLY. With no host or in dedicated-machine mode, the two-step path is available only while capabilities.servers.create.available is true; select an allowed plan ID from capabilities.servers.create.limits.allowedPlans. When an existing host is unsuitable, wait for it to recover, ask an administrator to repair it, or upgrade the plan before retrying one-shot creation. While available is false, do not switch to a dedicated machine: with trial enforcement active, the occupied slot returns 402 TRIAL_PORTAL_LIMIT. After removing the host, re-read GET /v1/me and use the two-step path advertised there.

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 and plan are required by the schema for a create without source. region is optional: omit it and the platform resolves the chosen provider's default region. For a Galaxy application the values are informational — the app inherits its host's provider, plan and region.

When a value you sent differs from the one the app actually got, the response carries an entry in warnings[] next to data: it names the diverging fields, shows both the value you sent and the one in force, and warns that re-sending will change nothing. Fields that matched are not mentioned, so a correct call stays free of warnings. If you need a machine whose provider, plan and region you choose, create it with placement set to dedicated.

A dedicated virtual machine instead of a Galaxy app

If your Bitrix24 account places apps in galaxies but this particular app needs its own server, pass the placement field set to dedicated. The provider + plan pair is required in that case; region stays optional. A source field in such a request returns 400 SOURCE_AT_CREATE_GALAXY_ONLY: a dedicated virtual machine is deployed in two steps, and the code is uploaded via POST /:id/deploy.

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-small",
    "region": "bc-eu-central",
    "placement": "dedicated"
  }'

The response carries kind set to STANDALONE. From there the dedicated virtual machine flow applies: wait for status: "running" and blackholeStatus: "CONNECTED", then deploy.

Diagnostics and environment variables

• The provisionError field. If the build or startup failed, GET /v1/infra/servers/:id returns the failure reason in data.provisionError — plus the tail of the Docker build log when the image build failed. 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. The platform passes PORT alongside them (equal to the port field, 3000 by default): the PORT key is reserved, your own value is overridden, and the response carries a warnings[] entry — see POST /v1/infra/servers/:id/deploy. 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

data.sleepAfterMinutes is a response field, not a create parameter. To change the saved policy after creating a dedicated machine, call PATCH /v1/infra/servers/:id/sleep. Do not substitute the expected default for this field: on reuse or idempotency replay the response carries the existing record's value, including null or a historical numeric value. It is not a computed effective timeout: enabled wake-schedule windows must be deleted or disabled before null can be set, and once null is stored every schedule create/update is rejected, including a disabled window. If a reuse or replay exposes an older conflicting record with an effective schedule, the platform's post-window fallback applies — 15 minutes by default.

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",
    "sleepAfterMinutes": 60,
    "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",
    "sleepAfterMinutes": 60,
    "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",
    "sleepAfterMinutes": 60,
    "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 required provider + plan pair. The region field is optional and defaults to the chosen provider's region. For RUNTIME_PARAM_REMOVED the hint arrives when runtime is passed without source, even if provider and plan are filled in. On a Bitrix24 account with dedicated virtual machines there is no hint in either case.

During trial access, these early hints use the same advisory assessment as GET /v1/me. A host that is suitable according to stored state produces a recommendation to try the one-shot request. With no host, the two-step path is available only while capabilities.servers.create.available is true. When an existing host is unsuitable, wait for recovery, repair the host, or upgrade the plan before retrying one-shot creation; after removing the host, re-read GET /v1/me and use the two-step path advertised there. The hint is advisory: the POST makes the final decision.

When a request carrying source has already reached the actual placement check and returns SOURCE_AT_CREATE_GALAXY_ONLY, its error.hint reflects that result. With an existing host during trial access, the hint rules out the two-step path while capabilities.servers.create.available is false: with trial enforcement active, that path returns 402 TRIAL_PORTAL_LIMIT. With no host, it permits creating a dedicated machine without source and deploying afterwards only after that capability check succeeds.

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",
    "hint": {
      "reason": "This portal places new apps on shared galaxy hosts, and the request lacked `source` and the required provider/plan pair. `region` is optional and defaults to the provider's region.",
      "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 and plan (region is optional and defaults to the provider's region) 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\" with provider and plan; region is optional.",
      "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 the required provider and plan while keeping the dedicated server; region may be omitted to use the provider default, instead of moving the application into a galaxy container.

Reusing the application's server

The calling key belongs to an application from the Applications section, and an application can have exactly one server bound to it. When a server is already bound and running, POST /v1/infra/servers does not create a second one — it returns 201 with the server that is already there. The name you sent plays no part in that decision: the deduplication key is the calling key, not the name.

On a reuse response (reused: true) every data field describes the existing bound server, not your request — status, provider, plan, region, image, createdVia, createdAt all belong to it. The status can be anything, so waiting for "running" is not a check that the server is yours. The check is reused plus the name ⊕ requestedName pair.

Such a response always carries data.reused: true and, next to data, a warnings array with at least one entry. Compare data.name with data.requestedName — they differ whenever the application's server was created earlier under a different name.

What to do before deploying. Call GET /v1/infra/servers/:id and inspect what is already deployed there. A deploy replaces the code currently running — it is not additive. If this is not the server you intended, stop and ask the user which application this key should be working on.

About the source you sent. A one-shot create builds your source onto a reused Galaxy application only when it has no container yet (never deployed, or its last build failed) — the response then carries deploying: true, and you poll GET /v1/infra/servers/:id until running. In every other case, including a reused dedicated virtual machine, the archive is discarded and the response carries sourceIgnored: true — deploy it explicitly via POST /v1/infra/servers/:id/deploy once you have confirmed the server is the one you want.

About the displayName and description you sent. A reuse never renames the server it hands back: it keeps its own name and description, and the values you sent are discarded — the response shows this as data.metaIgnored: true plus a dedicated warning. Rename it deliberately with PATCH /v1/infra/servers/:id once you have confirmed the server is the right one.

About data.next. On a reuse response the field arrives only when there is nothing to overwrite on the returned server — a Galaxy application with no container that is still attached to its galaxy host. When there is no container but the app is detached from its host, there is nowhere to deploy, so next does not arrive either. When the server can run code, next is deliberately absent — the missing recommendation is the signal: work out whether this is the right server first. Do not read its absence as an error.

How to get a different server for the application. There is no separate call that changes the binding. When you need a dedicated virtual machine and want the binding left alone, create it with placement: "dedicated" — reuse does not fire, but the new server is not bound to the application either. When you need to change the bound server itself, delete the current one via DELETE /v1/infra/servers/:id: the next POST /v1/infra/servers with the same key then clears the stale binding and binds the newly created server. Deletion is irreversible and destroys everything deployed on the server — confirm via GET /v1/infra/servers/:id that it is not someone else's work first.

A create with placement: "dedicated" is not affected by reuse.

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 Bitrix24 accounts that place applications in galaxies, 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.
• The key does not protect against a repeated build on a reused server. A reused: true response is not stamped with the key, so retrying a request that carries source against a reused Galaxy application that has no container yet starts the build again. Poll GET /v1/infra/servers/:id first.

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. If the requested zone has run out of IP addresses (Address space exhausted), 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. In Bitrix24 Cloud, a capacity fallback may select another availability zone inside the same public region; in that case data.region does not change.
• 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.
• A new regular machine gets a 60-minute auto-sleep timeout. The actual saved value is returned immediately in data.sleepAfterMinutes by the create response and later by GET /v1/infra/servers/:id. On reuse and idempotency replay this is the existing record's value, so it can be null or differ from 60. Inbound HTTP requests and SSH activity reset the timer; cron, background processes, and the application's own outbound requests do not. For the allowed values and deliberate disabling of auto-sleep through PATCH with null, see Configure auto-sleep.
• The runtime is installed at the deploy stage. The runtime parameter without source is not accepted in POST /v1/infra/servers (it will return 400 RUNTIME_PARAM_REMOVED). Specify runtime in the body of POST /:id/deploy — for a dedicated virtual machine, the pipeline begins in the order runtime → stop_existing → clean → download → install. Together with source the runtime is accepted and required: that is the one-shot Galaxy application create, where runtime and start go in the same request.
• Non-ASCII characters in displayName and description from Windows PowerShell. Sent without explicit UTF-8 serialization, they are stored as question marks (?): the bytes are lost on the client side, before the request is sent. A ready-to-run call with UTF8.GetBytes — Windows / PowerShell and UTF-8.

See also

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