#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.tech. 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.tech/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, delete (4 endpoints).
• Lifecycle — start, stop, sleep, wake, tunnel repair, provisioning status (9 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).

#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.
6. The Bitrix24 plan plays a dual role. First, the Bitrix24 REST API itself is available only on commercial portal plans — without it 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 an active BitrixGPT + Marketplace subscription on the portal. 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 portal 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.tech/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": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

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

# 3. Deploy the application (?stream=false — JSON instead of SSE)
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/deploy?stream=false" \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -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.tech — the appUrl field in the /deploy response.

#curl — OAuth application

# Same thing, just add the Authorization: Bearer header with the session token
curl -X POST https://vibecode.bitrix24.tech/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": "ru-central1-b", "image": "fd83esfomhq25p2ono90" }'

#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.tech/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  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 === 'ru-central1-b')
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)
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' },
})

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 })

#Endpoint reference

All 35 endpoints. Links lead to pages with parameters, examples, and error codes.

Providers and catalogs:

Servers:

Lifecycle:

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 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 portal 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 on the portal 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 an active BitrixGPT + Marketplace subscription on the portal:

• 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 an 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 the BitrixGPT + Marketplace subscription on the portal.

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

#Access-gate and billing errors

#System errors

The full reference of common errors — Errors.

#See also

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