#Infrastructure

Create and manage virtual servers for deploying Bitrix24 applications. Each server is invisible from the internet by default (Black Hole mode) — the application is reachable only through the HTTPS subdomain app-{id}.vibecode.bitrix24.com. Server management and deployment go through the REST API without SSH.

Scope: vibe:infra (added automatically to every API key) · Base URL: https://vibecode.bitrix24.com/v1 · Authorization: X-Api-Key header

#Documentation sections

• Providers and catalogs — list of providers, plans, regions, and OS images (4 endpoints).
• Servers — create, list, details, update name and description, delete (5 endpoints).
• Lifecycle — start, stop, sleep, wake, tunnel repair, provisioning status (9 endpoints).
• Scheduled wake — recurring wake windows for a sleeping server on a cron schedule (4 endpoints).
• Access and modes — access policy, user/department list, SSH credentials, BLACKHOLE↔OPEN mode (7 endpoints).
• Deploy API — run commands, upload files, deploy the application, logs, port, metrics, lock, runtimes (8 endpoints).
• Access tokens — short-lived tokens for e2e checks and shareable links (3 endpoints).
• What arrives at the application — Gateway injection of X-Vibe-Authorization: Bearer, reading identity via /v1/me, handler skeletons in Node/Python/Go.
• Portal event subscriptions — delivery of Bitrix24 events (ONTASKADD and similar) to the app through the tunnel, without polling (3 endpoints).
• Galaxy app — the "container in a shared galaxy" placement model: how to tell it from a regular server (kind), the build-on-upload lifecycle, per-galaxy pricing.
• Server access recovery — the server is running but a new key cannot see it: an empty list, 404 NOT_FOUND, changing the managing key.

#What to know up front

1. The application port is always 3000. The Black Hole tunnel proxies exactly this port; you don't need to change it. The server is an isolated environment: :3000 inside the virtual machine has no relation to the ports on your local machine.
2. Deploy API is BLACKHOLE-only. All of /deploy, /exec, /upload, /logs require servers in BLACKHOLE mode with the tunnel agent in status CONNECTED. For OPEN servers they return an error.
3. /deploy and /exec return JSON by default. This is safe for AI agents and MCP clients — no extra query parameters are needed. If you genuinely need a streaming response (live deploy-step output in the UI), pass ?stream=true — then you get SSE (Server-Sent Events). The documentation used to claim the opposite (SSE by default, ?stream=false for JSON) — that is outdated and no longer matches the API behavior.
4. accessPolicy is security. Changing the policy from OWNER_ONLY to PORTAL/AUTHENTICATED/PUBLIC opens the application to other users. Never change accessPolicy without explicit user confirmation.
5. The server is a clean Ubuntu 24.04 with root access enabled. The virtual machine is created from a stock Ubuntu image with no preinstalled software (except the tunnel agent). The agent runs as the root user — no sudo is needed in preStart, install, or /exec commands. Outbound internet is unrestricted: apt-get, curl, wget, pip work directly. Inbound traffic is blocked except the tunnel connection. The app itself, however, does not run as root — it runs under a dedicated unprivileged account. This applies to the app process only. Deploy commands and /exec still run with administrator privileges. Details and how to opt out — Deploying an app.
6. The Bitrix24 plan plays a dual role. First, the Bitrix24 REST API itself is available only on commercial Bitrix24 account plans — without one, neither applications, nor the /v1/deals proxy, nor bots, nor any other call proxied into Bitrix24 work. Second, on top of that — creating servers, deploying, and waking require a qualifying Bitrix24 plan: a commercial plan grants full access, a demo plan grants a limited trial, and a free plan is declined with INT_TARIFF_REQUIRED. This is an AI Beta; terms may change at any time. AI Router works independently of the Bitrix24 plan — it does not proxy into REST and is available even on free plans (BYOK free; platform models are billed against the Vibecode balance). Details are in the "Plan and access" section below.
7. User authorization inside the application. On every request the Gateway injects six headers prefixed with X-Vibe-: Request-Id always, plus User-Id, User-Name, User-Role, Portal-Id, Authorization (Bearer vibe_session_<…>) for an authenticated request. The browser never sees or stores the Authorization token — it lives only between the Gateway and the app server. For a quick user identifier the X-Vibe-User-Id header is enough; the full context (scopes, capabilities, plan, application info) comes from a single GET /v1/me call with server-side caching. The user ID in the /v1/me response is data.currentUser.bitrixUserId; the Bitrix24 account domain is data.portal. The full header table, the BFF pattern, and handler skeletons in Node/Python/Go — What arrives at the application.
8. Creating servers requires a user session for vibe_app_ keys. POST /v1/infra/servers is gated by a plan check that needs to know exactly who is creating the server. For vibe_api_ the user context already lives in the key itself; for vibe_app_ an Authorization: Bearer <session> is required — without it the response is 401 UNAUTHENTICATED with an error.hint pointing at the OAuth flow. Reads and the Deploy API on already-existing servers don't require a session — the "Endpoint authorization" table below collects all the rules in one place.

#Quick start

Three calls — create a server and run the application.

#curl — personal key

export VIBE_KEY="YOUR_API_KEY"

# 1. Create a server (automatically in Black Hole mode)
curl -X POST https://vibecode.bitrix24.com/v1/infra/servers \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "bitrix-cloud",
    "name": "my-app",
    "plan": "bc-small",
    "region": "bc-eu-central",
    "image": "ubuntu-2404-lts"
  }'

# 2. Wait until ready: status=running AND blackholeStatus=CONNECTED
curl -H "X-Api-Key: $VIBE_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID

# 3. Deploy the application (?stream=false — JSON instead of SSE).
#    X-Skip-Source-Snapshot: deploy from an external URL while source
#    storage is enabled, otherwise 409 SNAPSHOT_REQUIRED (see below).
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy?stream=false" \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Skip-Source-Snapshot: deploy from external URL" \
  -d '{
    "source": { "url": "https://github.com/user/app/archive/main.tar.gz" },
    "runtime": "node20",
    "install": "cd /opt/app && npm install --production",
    "start": "cd /opt/app && node server.js",
    "port": 3000
  }'

The application is reachable at https://app-{id}.vibecode.bitrix24.com — the appUrl field in the /deploy response.

Deploying from an external URL and source storage. When source storage is enabled for your Bitrix24 account, a deploy from an external address — not from Vibecode storage — returns 409 SNAPSHOT_REQUIRED so that the application's version history is not lost. The X-Skip-Source-Snapshot: <reason> header continues the deploy without saving a snapshot. To keep a snapshot, first upload the archive via POST /v1/apps/:id/sources, then deploy it via { "source": { "versionId": "vN" } }. More details — Source storage.

#curl — OAuth application

# Same thing, just add the Authorization: Bearer header with the session token
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-app", "plan": "bc-small", "region": "bc-eu-central", "image": "ubuntu-2404-lts" }'

#Full example

A realistic JavaScript scenario — create a server, wait until ready, deploy, get the application URL.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null, extraHeaders = {}) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY, ...extraHeaders } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}`)
  return res.json()
}

// 1. Pick provider, plan, region, image
const { data: plans } = await api('GET', '/infra/providers/bitrix-cloud/plans')
const { data: regions } = await api('GET', '/infra/providers/bitrix-cloud/regions')
const { data: images } = await api('GET', '/infra/providers/bitrix-cloud/images')

const plan = plans.find(p => p.id === 'bc-small')
const region = regions.find(r => r.id === 'bc-eu-central')
const image = images[0]

// 2. Create a server (always in Black Hole)
const { data: server } = await api('POST', '/infra/servers', {
  provider: 'bitrix-cloud',
  name: 'my-crm-bot',
  plan: plan.id,
  region: region.id,
  image: image.id,
})
console.log(`Server created: ${server.id}, subdomain: ${server.subdomain}`)

// 3. Wait until status becomes running AND blackholeStatus becomes CONNECTED
let info = server
while (info.status !== 'running' || info.blackholeStatus !== 'CONNECTED') {
  await new Promise(r => setTimeout(r, 10000)) // 10 seconds between polls
  const res = await api('GET', `/infra/servers/${server.id}`)
  info = res.data
  console.log(`status=${info.status}, blackhole=${info.blackholeStatus}`)
}

// 4. Deploy the application (?stream=false is required for a JSON response).
//    The X-Skip-Source-Snapshot header is needed when deploying from an
//    external URL while source storage is enabled — otherwise 409 SNAPSHOT_REQUIRED.
const deploy = await api('POST', `/infra/servers/${server.id}/deploy?stream=false`, {
  source: { url: 'https://github.com/user/app/archive/main.tar.gz' },
  runtime: 'node20',
  install: 'cd /opt/app && npm install --production',
  preStart: 'cd /opt/app && npx prisma migrate deploy',
  start: 'cd /opt/app && node server.js',
  port: 3000,
  env: { NODE_ENV: 'production' },
}, { 'X-Skip-Source-Snapshot': 'deploy from external URL' })

console.log(`Application is live: ${deploy.data.appUrl}`)

// 5. (Optional) Configure auto-sleep after 60 minutes of inactivity
await api('PATCH', `/infra/servers/${server.id}/sleep`, { sleepAfterMinutes: 60 })

Galaxy app — a different contract. If your Bitrix24 account places apps in galaxies, the same POST /v1/infra/servers creates a Galaxy app — a container on a shared host. Upload the code right after creation, without waiting for blackholeStatus: "CONNECTED". The full model, lifecycle, cost, and deploy differences — Galaxy app.

#Endpoint reference

Endpoint reference for the section. Links lead to pages with parameters, examples, and error codes.

Providers and catalogs:

Servers:

Lifecycle:

Scheduled wake:

Access and modes:

Deploy API:

Access tokens:

Portal event subscriptions:

#Endpoint authorization

All infra endpoints require the X-Api-Key header. For vibe_app_ keys (bound to an OAuth application) some POST operations additionally require Authorization: Bearer <session> — without it the response is 401 UNAUTHENTICATED with an error.hint. For vibe_api_ keys the user context already lives in the key itself, so a separate session is not needed.

Quick check before calling: GET /v1/me → data.capabilities.servers.create.available. For vibe_app_ without a session it returns false with reason: "SESSION_REQUIRED" and a hint in userMessage — the model immediately sees that it needs to go through the OAuth flow rather than hitting a 401 on the POST /v1/infra/servers itself.

#Limits

The platform rate limit is shared across all V1 endpoints, see the "Limits and optimization" section.

#Server statuses

The blackholeStatus field describes the agent tunnel state independently of status:

The kind field distinguishes the placement model: STANDALONE — a separate virtual machine, GALAXY_APP — a Galaxy app (a container in a galaxy), GALAXY — the galaxy itself (the host carrier; created by the platform, not the user). A Galaxy app's blackholeStatus stays NONE until the code is uploaded — it does not connect on its own. More details — Galaxy app.

The runtimeStatus field is deprecated, kept for compatibility. For servers created after 2026-04-25 (when the runtime parameter was removed from POST /v1/infra/servers) it always returns null. The runtime is now installed at the POST /:id/deploy stage, and the readiness signal is the success of the runtime step itself in the deploy response.

#Plan and access

Vibecode infrastructure has two levels of access conditions.

Level 1 — Bitrix24 REST API. Bitrix24 itself opens the REST API only on commercial Bitrix24 account plans. This is not about Vibecode: on free Bitrix24 plans it simply does not return REST responses. So without a commercial Bitrix24 plan the following do not work:

• Creating and publishing applications (POST /api/apps) — registered in the Bitrix24 account via REST.
• REST proxy: /v1/deals, /v1/contacts, /v1/batch, /v1/bots, /v1/tasks and all other entities.
• Bots, chats, tasks — everything proxied into Bitrix24.

Level 2 — Vibecode infrastructure. On top of the first condition, creating servers, deploying, and waking require a qualifying Bitrix24 plan — a commercial plan grants full access, a demo plan a limited trial, and a free plan is declined with INT_TARIFF_REQUIRED (this is an AI Beta; terms may change at any time):

• POST /v1/infra/servers — creating a server.
• POST /v1/infra/servers/:id/deploy — deploying the application.
• POST /v1/infra/servers/:id/wake and automatic waking when preventWake=true.
• Creating agents and managed bots (they provision servers under the hood).

What works on any Bitrix24 plan, including free:

• AI Router — POST /v1/chat/completions, POST /v1/audio/transcriptions, GET /v1/models. Does not proxy into Bitrix24, goes directly to LLM providers. With BYOK keys — free; with platform models — billed against the Vibecode balance.
• Basic platform endpoints: GET /v1/me, GET /v1/feedback, GET /v1/guide — for AI-agent self-orientation.

Check before calling: GET /v1/me → the capabilities.servers.create.available field. If false — the capabilities.servers.create.userMessage field contains a translated explanation for the user.

Force refresh after a plan upgrade: GET /v1/me?refresh=tariff — skips the cache (1 hour by default) and makes a fresh app.info request.

Access to servers: the single signal is capabilities.servers.create in the GET /v1/me response (see above). If access is closed, POST /v1/infra/servers returns 402 (or 403 for REGION_NOT_SUPPORTED) with the access-gate code (see "Error codes" below). Access is governed by your Bitrix24 plan: a commercial plan grants full access, a demo plan a limited trial, and a free plan is declined with INT_TARIFF_REQUIRED.

Response headers of the infra endpoints:

The access-gate error codes are listed in the "Error codes" section below.

#Error codes

#Infrastructure errors

#Deploy API errors

For /exec and /deploy on a separate virtual machine (kind: "STANDALONE"), the connection is held open for the whole run, so the 200 status is sent before the work starts. A failure during execution arrives in the response body — the marker is success: false, not the HTTP status. Check success, otherwise a failed command will be mistaken for a successful one. For a Galaxy app (kind: "GALAXY_APP") the same error arrives with the status 502 — the 200 HTTP statuses in the table above apply to a separate virtual machine.

In streaming mode (?stream=true) a failure arrives as an SSE error event with code and message — this is how /exec and a deploy report a failure on an exception or a transport drop. For a deploy, a failure of an individual step arrives differently — as a step event with status: "error" and the step name. There is no success field in the stream.

#Access-gate and billing errors

#System errors

The full reference of common errors — Errors.

#App icon

The app icon (SVG) appears in the Bitrix24 catalog and as the browser-tab favicon. The format, requirements and order (favicon <link> before deploy, POST /v1/infra/servers/:id/icon upload after) live on a dedicated page — App icon.

#Recipes

• Load a database dump onto a server — upload a dump and restore the database in the background via exec.
• A fast release cycle — shorten the edit cycle without running every step.

#See also

• API overview — overall platform architecture.
• Limits and optimization — rate limits, auto-pagination, batch requests.
• Keys and authorization (/v1/me) — plan and capability check.
• What arrives at the application — Gateway injection of X-Vibe-Authorization, BFF pattern, handler skeletons.