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

POST /v1/infra/servers

Создаёт приложение у облачного провайдера. Всегда в режиме Black Hole — iptables блокирует все входящие порты, приложение невидимо из интернета.

На портале есть две модели размещения, и от модели зависит, чего ждать после создания:

• Отдельная виртуальная машина (модель по умолчанию). Ответ возвращается сразу со статусом provisioning, провижининг занимает 1–3 минуты, после чего нужно опрашивать GET /v1/infra/servers/:id до status: "running" и blackholeStatus: "CONNECTED". Ответ единственный раз содержит SSH-данные ssh.password и ssh.privateKey — они будут нужны при переключении в режим OPEN, сохраните их сразу. Эта страница описывает данную модель в полях запроса, полях ответа и таблице ошибок ниже.
• Galaxy-приложение — контейнер на общем хосте. Если портал размещает приложения в галактиках, тот же POST /v1/infra/servers создаёт galaxy-приложение, а не виртуальную машину. Признак модели в ответе — поле createdVia равно galaxy. Раздел «Galaxy-приложение» ниже описывает два сценария запуска, полная модель — на странице Galaxy-приложение.

Galaxy-приложение

Если портал размещает приложения в галактиках, POST /v1/infra/servers создаёт galaxy-приложение — контейнер на общем хосте, а не отдельную виртуальную машину. Запрос и порядок вызовов те же, отличается жизненный цикл. Признак модели в ответе — поле createdVia равно galaxy. Полная модель, стоимость и отличия деплоя — на странице Galaxy-приложение.

Не ждите CONNECTED перед загрузкой кода. Galaxy-приложение никогда само не доходит до blackholeStatus: "CONNECTED" — его контейнер собирается при загрузке кода. Если просто опрашивать статус, приложение останется в provisioning, а примерно через 20 минут платформа пометит его как error и запишет в поле provisionError, что код так и не был загружен. Поэтому код загружают сразу — одним из двух сценариев ниже.

Сценарий 1 — прозрачный, рекомендуется

Один запрос. Передайте в POST /v1/infra/servers код приложения в поле source вместе с runtime и start (и при необходимости install, env, port). Сборка пойдёт в фоновом режиме. После ответа опрашивайте GET /v1/infra/servers/:id до status: "running". Отдельный вызов загрузки кода не нужен.

curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-crm-app",
    "displayName": "Мой CRM-бот",
    "source": { "content": "<base64-архив>" },
    "runtime": "node20",
    "start": "node index.js",
    "install": "npm ci",
    "port": 3000
  }'

Поля source, runtime, start, install, env, port, healthPath совпадают по смыслу с телом POST /:id/deploy:

Без полей runtime и start поле source вернёт 400 — оба поля обязательны. На портале без режима галактик source запрещён и вернётся 400 SOURCE_AT_CREATE_GALAXY_ONLY. Тот же ответ придёт на бесплатном тарифе Битрикс24, пока у аккаунта нет галактики: новая на бесплатном тарифе не создаётся, поэтому разворачивайте в два шага — создание без source, затем POST /v1/infra/servers/:id/deploy.

Сценарий 2 — в два шага

Создайте приложение без source — ответ придёт со статусом provisioning и подсказкой next: "deploy". Сразу вызовите POST /v1/infra/servers/:id/deploy с кодом в source, рантаймом и командой запуска. Загружайте код сразу, не дожидаясь CONNECTED.

# Шаг 1 — создать приложение без кода
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-medium", "region": "ru-central1-a" }'

# Ответ содержит data.id, data.next = "deploy" и data.hint.
# Шаг 2 — сразу загрузить код, не дожидаясь CONNECTED
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/deploy \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "content": "<base64-архив>" },
    "runtime": "node20",
    "start": "node index.js",
    "port": 3000
  }'

provider и plan обязательны по схеме для создания без source. region необязателен: без него платформа сама подставит регион по умолчанию для выбранного провайдера. Для galaxy-приложения значения информационны — приложение наследует провайдера, план и регион своего хоста.

Если присланное значение расходится с тем, что приложение реально получило, ответ несёт запись в warnings[] рядом с data: она называет разошедшиеся поля, показывает и присланное, и действующее значение и предупреждает, что повторная отправка ничего не изменит. Совпавшие поля не упоминаются, так что корректный вызов остаётся без предупреждения. Нужна машина, у которой провайдера, план и регион выбираете вы, — создавайте её с placement равным dedicated.

Отдельная виртуальная машина вместо galaxy-приложения

Если портал размещает приложения в галактиках, а конкретному приложению нужен свой сервер — передайте поле placement равным dedicated. Пара provider, plan при этом обязательна, region по-прежнему необязателен. Поле source в таком запросе вернёт 400 SOURCE_AT_CREATE_GALAXY_ONLY: отдельная виртуальная машина разворачивается в два шага, код загружают через POST /:id/deploy.

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",
    "placement": "dedicated"
  }'

В ответе kind равен STANDALONE. Дальше действует порядок для отдельной виртуальной машины: дождаться status: "running" и blackholeStatus: "CONNECTED", затем деплой.

Диагностика и переменные окружения

• Поле provisionError. Если сборка или запуск упали, GET /v1/infra/servers/:id вернёт в data.provisionError причину сбоя, а при ошибке сборки образа — ещё и хвост лога сборки Docker. Читайте это поле, чтобы понять причину.
• Переменные env подставляются при запуске. Значения из env передаются в контейнер во время запуска через docker run --env, а не вшиваются в образ. Вместе с ними платформа передаёт PORT (равен полю port, по умолчанию 3000): ключ PORT зарезервирован, присланный свой перекрывается, и ответ несёт строку в warnings[] — см. POST /v1/infra/servers/:id/deploy. Поэтому ключи API и секреты из env не попадают в слои образа.

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

Примечание: для модели отдельной виртуальной машины параметр runtime в POST /v1/infra/servers не принимается — передача вернёт 400 RUNTIME_PARAM_REMOVED. Рантайм устанавливается на этапе деплоя. См. POST /:id/deploy. Исключение — режим галактик: при передаче поля source параметр runtime обязателен (см. раздел «Galaxy-приложение»), и 400 RUNTIME_PARAM_REMOVED в этом случае не возвращается.

Примеры

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

# name — только строчные латинские буквы, цифры и дефис, первый символ буква (^[a-z][a-z0-9-]*$)
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",
    "displayName": "Мой CRM-бот",
    "plan": "bc-small",
    "region": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

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

# name — только строчные латинские буквы, цифры и дефис, первый символ буква (^[a-z][a-z0-9-]*$)
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",
    "displayName": "Мой CRM-бот",
    "plan": "bc-small",
    "region": "ru-central1-b",
    "image": "fd83esfomhq25p2ono90"
  }'

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

// name — только строчные латинские буквы, цифры и дефис, первый символ буква (^[a-z][a-z0-9-]*$)
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',
    displayName: 'Мой CRM-бот',
    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-приложение

// name — только строчные латинские буквы, цифры и дефис, первый символ буква (^[a-z][a-z0-9-]*$)
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',
    displayName: 'Мой CRM-бот',
    plan: 'bc-small',
    region: 'ru-central1-b',
    image: 'fd83esfomhq25p2ono90',
  }),
})

Поля ответа

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

Отдельная виртуальная машина:

{
  "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-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"
  }
}

Galaxy-приложение по сценарию 1 — source передан, сборка идёт в фоне. Полей ssh и next нет:

{
  "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": "Мой CRM-бот",
    "ip": null,
    "ssh": null,
    "plan": "bc-medium",
    "region": "ru-central1-a",
    "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.tech",
    "createdAt": "2026-04-22T10:50:11.477Z"
  }
}

Galaxy-приложение по сценарию 2 — source не передан, появляются next и hint:

{
  "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": "Мой CRM-бот",
    "ip": null,
    "ssh": null,
    "plan": "bc-medium",
    "region": "ru-central1-a",
    "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.tech",
    "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."
  }
}

Если сборка galaxy-приложения упала, GET /v1/infra/servers/:id вернёт причину в 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"
  }
}

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

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

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

Ошибки

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

Подсказка `error.hint`

На портале с размещением в галактике ошибки INVALID_REQUEST и RUNTIME_PARAM_REMOVED дополняются объектом error.hint. Он называет причину отказа и даёт готовое тело запроса. Условие у двух кодов разное. У INVALID_REQUEST подсказка приходит, когда в теле нет ни source, ни полной тройки provider + plan + region. У RUNTIME_PARAM_REMOVED — когда передан runtime без source, причём тройка при этом может быть заполнена полностью. На портале с отдельными виртуальными машинами подсказки нет ни в одном из случаев.

Не путайте с data.hint из успешного ответа: там строка про следующий шаг после создания приложения по сценарию 2, здесь — объект внутри 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 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
      }
    }
  }
}

Если в теле передан placement: "dedicated", подсказка другая: она предлагает добавить provider, plan и region, сохранив выделенный сервер, а не переводить приложение в контейнер галактики.

Переиспользование сервера приложения

Ключ вызова принадлежит приложению из раздела «Приложения», и приложению можно привязать ровно один сервер. Если сервер уже привязан и работает, POST /v1/infra/servers не создаёт второй, а возвращает 201 с уже существующим сервером. Имя, которое вы передали в name, в этом решении не участвует — повтор платформа определяет по вызывающему ключу, а не по имени.

В reuse-ответе (reused: true) все поля data описывают существующий привязанный сервер, а не ваш запрос — status, provider, plan, region, image, createdVia, createdAt относятся к нему. Статус может быть любым, поэтому «дождаться running» не является проверкой того, что сервер ваш. Проверка — это reused и пара name ⊕ requestedName.

Ответ на такой запрос всегда несёт data.reused: true и рядом с data — массив warnings минимум с одной записью. Сравните data.name с data.requestedName: они различаются, если сервер приложения был создан раньше и под другим именем.

Что делать перед деплоем. Запросите GET /v1/infra/servers/:id и посмотрите, что на сервере уже развёрнуто. Деплой заменяет работающий код, он не добавляет к нему. Если это не тот сервер, который вы имели в виду, остановитесь и спросите пользователя, с каким приложением должен работать этот ключ.

Про переданный source. Одношаговое создание разворачивает исходники в переиспользуемое galaxy-приложение только тогда, когда контейнера ещё нет (ни разу не деплоилось, либо прошлая сборка упала) — в ответе будет deploying: true, опрашивайте GET /v1/infra/servers/:id до running. Во всех остальных случаях, включая переиспользованную отдельную виртуальную машину, архив отбрасывается и в ответе появляется sourceIgnored: true — разверните его явно через POST /v1/infra/servers/:id/deploy, когда убедитесь, что сервер тот.

Про переданные displayName и description. Переиспользование никогда не переименовывает сервер, который отдаёт: у него остаются собственные имя и описание, а переданные вами значения отбрасываются — в ответе это видно по data.metaIgnored: true и отдельному предупреждению. Переименуйте осознанно через PATCH /v1/infra/servers/:id, убедившись, что сервер тот.

Про data.next. В reuse-ответе поле приходит только тогда, когда на возвращённом сервере нечего перезаписывать — это galaxy-приложение без контейнера, прикреплённое к своему galaxy-хосту. Если контейнера нет, но приложение откреплено от хоста, деплоить некуда — next тоже не придёт. Если сервер может выполнять код, next в ответе отсутствует намеренно — отсутствие рекомендации и есть сигнал: сначала разберитесь, тот ли это сервер. Не трактуйте отсутствие next как ошибку.

Как получить для приложения другой сервер. Отдельного вызова, меняющего привязку, нет. Если нужна отдельная виртуальная машина и привязку трогать не надо — создайте её с placement: "dedicated": переиспользование не сработает, но и к приложению новый сервер привязан не будет. Если нужно именно сменить привязанный сервер — удалите текущий через DELETE /v1/infra/servers/:id, и следующий POST /v1/infra/servers тем же ключом снимет устаревшую привязку и привяжет вновь созданный сервер. Удаление необратимо и уничтожает всё, что развёрнуто на сервере, — сначала убедитесь по GET /v1/infra/servers/:id, что это не чужая работа.

Создание с placement: "dedicated" переиспользование не затрагивает.

Идемпотентность

Передайте необязательный заголовок Idempotency-Key, чтобы безопасно повторять создание отдельного сервера (standalone). Если ответ на первый запрос потерялся (обрыв сети, таймаут балансировщика), повтор с тем же ключом не создаст второй сервер — вернётся тот же самый сервер, что и в первый раз, со статусом 201 и заголовком ответа Idempotent-Replayed: true.

• Ключ — строка 1–255 символов из набора [A-Za-z0-9_.:-]. Область действия — ваш API-ключ.
• При повторе одноразовые SSH-данные не выдаются повторно. В теле ответа ssh.privateKey и ssh.password будут null, а поле note пояснит это. Сохраняйте данные из ответа первого создания.
• Заголовок работает только для standalone-серверов. На порталах с размещением в галактике корректный ключ игнорируется без ошибки, и защита от повторного создания на этот путь не распространяется.
• Заголовок несовместим с graduateFrom для выделенного сервера — вернётся 400 IDEMPOTENCY_UNSUPPORTED_WITH_GRADUATION.
• Ключ не защищает от повторной сборки на переиспользованном сервере. Ответ с reused: true ключом не помечается, поэтому повтор запроса с source на переиспользованное galaxy-приложение, у которого ещё нет контейнера, запустит сборку заново. Сначала опросите GET /v1/infra/servers/:id.

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

• Примеры корректных и некорректных имён по паттерну ^[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.
• Таймаут провижининга — 15 минут. Если status держится в provisioning дольше, платформа переводит сервер в error и заполняет provisionError и provisionErrorCode. Дальше остаётся вызвать DELETE и создать новый.
• Рантайм устанавливается на этапе деплоя. Параметр runtime был удалён из POST /v1/infra/servers (вернёт 400 RUNTIME_PARAM_REMOVED). Указывайте runtime в теле POST /:id/deploy — он установится между извлечением архива и запуском приложения.
• Кириллица в displayName и description из Windows PowerShell. Отправленная без явной сериализации в UTF-8, она сохраняется знаками вопроса (?): байты теряются на стороне клиента, до отправки запроса. Готовый вызов с UTF8.GetBytes — Windows / PowerShell и UTF-8.

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

• Провайдеры и каталоги
• Получить сервер
• Список серверов
• Обновить имя и описание
• Удалить сервер
• Deploy API
• Полный деплой приложения
• Список рантаймов
• Тариф и доступ
• Режим доступа