#Создать сервер

POST /v1/infra/servers

Создаёт виртуальный сервер у облачного провайдера. Всегда в режиме Black Hole — iptables блокирует все входящие порты, сервер невидим из интернета. Провижининг занимает 1–3 минуты: ответ возвращается сразу со статусом provisioning, после чего нужно опрашивать `GET /v1/infra/servers/:id` до status: "running" и blackholeStatus: "CONNECTED". Ответ единственный раз содержит SSH-креды (ssh.password, ssh.privateKey) — они будут нужны при переключении сервера в режим OPEN; сохраните их сразу.

#Поля запроса (body)

Поле Тип Обяз. Описание
provider string да ID провайдера из `GET /v1/infra/providers`, например bitrix-cloud. 1–50 символов
name string да Имя сервера. 2–63 символа, только строчные латинские буквы, цифры и -, первым символом — буква. Паттерн: ^[a-z][a-z0-9-]*$
plan string да ID тарифа из `GET /v1/infra/providers/:providerId/plans`, например bc-small
region string да ID региона из `GET /v1/infra/providers/:providerId/regions`, например ru-central1-b
image string да ID образа ОС из `GET /v1/infra/providers/:providerId/images`. Берите актуальный из ответа — ID меняется при обновлении сборки
sshPublicKey string нет Ваш SSH-публичный ключ (ssh-rsa …, ssh-ed25519 …, ecdsa-sha2-nistp256/384/521 …, security-keys). До 8192 символов. Если не передан — платформа сгенерирует приватный ключ и вернёт его один раз в ssh.privateKey

Примечание: параметр runtime удалён из POST /v1/infra/servers — передача вернёт 400 RUNTIME_PARAM_REMOVED. Рантайм устанавливается на этапе деплоя. См. POST /:id/deploy.

#Примеры

#curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

#curl — OAuth-приложение

Terminal 
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-crm-app",
    "plan": "bc-small",
    "region": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

#JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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',
    plan: 'bc-small',
    region: 'ru-central1-b',
    image: 'fd83esfomhq25p2ono90',
  }),
})
const { data } = await res.json()
console.log('Server ID:', data.id, 'Subdomain:', data.subdomain)

// Сохраняем SSH-креды на всякий случай — они возвращаются только один раз
if (data.ssh.privateKey) {
  await saveLocally(`${data.id}.key`, data.ssh.privateKey)
}

#JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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',
    plan: 'bc-small',
    region: 'ru-central1-b',
    image: 'fd83esfomhq25p2ono90',
  }),
})

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.id string (UUID) Уникальный идентификатор сервера
data.status string Всегда "provisioning" сразу после создания. Ждите "running" через 1–3 минуты
data.provider string Эхо переданного provider
data.name string Эхо переданного name
data.ip string | null Публичный IP. null сразу после создания, заполнится когда виртуальная машина запустится
data.ssh.user string Пользователь для SSH: root для новых серверов
data.ssh.port number Порт SSH: 22
data.ssh.password string | null Одноразово! Пароль root. Сохраняйте сразу — позже не вернётся. Нужен при переключении в OPEN-режим
data.ssh.privateKey string | null Одноразово! Приватный ключ в формате OpenSSH (если sshPublicKey не передавали при создании). Сохраняйте сразу
data.plan string Эхо переданного plan
data.region string Регион, в который сервер реально попал. Может отличаться от запрошенного при срабатывании зон-фолбэка (см. «Известные особенности»)
data.image string Эхо переданного image
data.mode string Всегда "BLACKHOLE" сразу после создания
data.createdVia string "api" для вызовов через v1 API, "ui" для вызовов из личного кабинета
data.subdomain string Субдомен для приложения, например app-92fb1c34. Используется в appUrl
data.blackholeStatus string Состояние туннеля агента. Сразу после создания — "NONE", затем проходит через WAITING и завершается CONNECTED
data.accessPolicy string Политика доступа к приложению. По умолчанию "OWNER_ONLY" — только владелец ключа
data.runtimeId string | null Всегда null при создании. Заполняется при деплое с runtime
data.runtimeStatus string | null Всегда null при создании. Обновляется во время деплоя
data.appUrl string | null HTTPS-адрес приложения: https://{subdomain}.vibecode.bitrix24.tech
data.createdAt string (ISO 8601) Момент создания

#Пример ответа

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

#Пример ответа при ошибке

400 — нарушена валидация (имя начинается с заглавной):

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

#Ошибки

HTTP Код Описание
400 INVALID_REQUEST Нарушена валидация полей (неверный формат имени, отсутствует обязательное поле, неверный SSH-ключ и т. д.). Поле message содержит конкретную причину
400 RUNTIME_PARAM_REMOVED Параметр runtime удалён. Указывайте рантайм в `POST /:id/deploy`
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
402 COMMERCIAL_PLAN_REQUIRED Бесплатный тариф Битрикс24 и trial недоступен (уже использован). См. тарифный gate
402 TRIAL_EXPIRED Trial использован и завершился
402 TRIAL_PORTAL_LIMIT Превышена квота серверов портала на trial
402 TRIAL_USER_LIMIT Превышена квота серверов на пользователя на trial
402 PLAN_NOT_ALLOWED_ON_TRIAL На trial разрешён только тариф bc-micro
402 ACCOUNT_FROZEN Баланс Вайбкод заморожен, нужно пополнить
403 INFRA_NOT_PERMITTED Инфраструктура отключена на платформе или на портале
403 SERVER_CREATION_DISABLED Создание серверов запрещено политикой портала
403 MAX_SERVERS_REACHED Превышен лимит серверов на API-ключ (по умолчанию 3). Удалите ненужные через `DELETE` или создавайте новый API-ключ
404 NO_CREDENTIALS Провайдер provider не сконфигурирован на платформе
502 PROVIDER_ERROR Облачный провайдер вернул ошибку при создании виртуальной машины. Запись сервера помечается как удалённая, квота не расходуется — можно сразу повторить попытку. Поле message содержит текст от провайдера
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

Полный список общих ошибок API — Ошибки.

#Известные особенности

  • Примеры корректных и некорректных имён по паттерну ^[a-z][a-z0-9-]*$:
    • Правильно: my-app, bot-1, crm-dashboard.
    • Неправильно: My-App (заглавная), bot_1 (подчёркивание), my.app (точка), кириллица.
  • sshPublicKey vs автогенерация. Если передаёте свой публичный ключ — платформа не генерирует приватный, и ssh.privateKey в ответе будет null. Пароль в ssh.password всё равно возвращается.
  • Когда region в ответе отличается от запрошенного. В запрошенной зоне могли кончиться IP-адреса (Address space exhausted) — тогда платформа автоматически пробует следующие зоны в порядке из `GET /v1/infra/providers/:providerId/regions`, и фиксирует это в аудит-логе событием SERVER_ZONE_FALLBACK.
  • Таймаут провижининга — 10 минут. Если status застрял в provisioning дольше, система сама вернёт сервер в sleeping с preventWake: true, после чего остаётся вызвать `DELETE` и создать новый.
  • Рантайм устанавливается на этапе деплоя. Параметр runtime был удалён из POST /v1/infra/servers (вернёт 400 RUNTIME_PARAM_REMOVED). Указывайте runtime в теле `POST /:id/deploy` — он установится между извлечением архива и запуском приложения.

#Смотрите также