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

POST /v1/infra/servers

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

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

• Отдельная виртуальная машина (модель по умолчанию). Если под выбранный тариф есть заранее подготовленная машина, платформа настраивает её и только потом отвечает — уже со статусом running и с IP-адресом. Иначе платформа отвечает сразу со статусом 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:

Других полей деплоя одношаговое создание не принимает: preStart, systemd, serviceName, cleanDeploy, extractTo, hardening, preserveEnv, dataDirs, dataDirsRecursive вернут 400 UNKNOWN_PARAM, а полный список допустимых полей придёт в details.validParams. Эти поля относятся к деплою отдельной виртуальной машины и к galaxy-приложению не применяются — команды, которые нужно выполнить до старта приложения, задавайте в install.

Без полей runtime и start поле source вернёт 400 — оба поля обязательны. На портале без режима галактик новый запрос с source запрещён и вернёт 400 SOURCE_AT_CREATE_GALAXY_ONLY. Повтор, который безопасно сходится на уже создаваемом keyless GALAXY_APP, выполняет это схождение раньше fresh-only отказа: возвращает прежний id с sourceIgnored: true и не запускает вторую сборку.

На пробном периоде сначала прочитайте блоки deployment и capabilities.servers.create из GET /v1/me. Если galaxyApp присутствует, одношаговое создание стоит попробовать, но этот блок отражает сохранённое состояние и не гарантирует успех: текущую вместимость проверяет только POST. Если режима галактик нет, placementNote отсутствует, а запрос с source возвращает 400 SOURCE_AT_CREATE_GALAXY_ONLY. При отсутствии хоста и в режиме отдельной машины двухшаговый путь разрешён, только когда capabilities.servers.create.available равен true; допустимый идентификатор тарифа выберите из capabilities.servers.create.limits.allowedPlans. Если существующий хост непригоден, для нового one-shot запроса дождитесь его восстановления, попросите администратора починить его либо повысьте тариф. Пока available равен false, не переходите на отдельную машину: при включённом контроле trial-ограничений занятый слот даёт 402 TRIAL_PORTAL_LIMIT. После удаления хоста заново прочитайте GET /v1/me и используйте объявленный там двухшаговый путь.

Сценарий 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',
  }),
})

Поля ответа

data.sleepAfterMinutes — поле ответа, а не параметр создания. Чтобы изменить сохранённую политику после создания отдельной машины, вызовите PATCH /v1/infra/servers/:id/sleep. Не подставляйте в это поле ожидаемый дефолт: при reuse или idempotency replay ответ возвращает значение уже существующей записи, в том числе null или историческое числовое значение. Поле не является вычисленным фактическим таймаутом: при null и действующем расписании пробуждения применяется платформенный запас после окна, по умолчанию 15 минут.

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

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

{
  "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",
    "sleepAfterMinutes": 60,
    "runtimeId": null,
    "runtimeStatus": null,
    "appUrl": "https://app-92fb1c34.vibecode.bitrix24.tech",
    "createdAt": "2026-04-22T10:50:11.477Z"
  }
}

У заранее подготовленной машины в этом ответе status равен running, а ip заполнен.

Galaxy-приложение по сценарию 1 — source передан, сборка идёт в фоне. Поле ssh равно null. Поля 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",
    "sleepAfterMinutes": 60,
    "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",
    "sleepAfterMinutes": 60,
    "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, причём provider и plan при этом могут быть заполнены. На портале с отдельными виртуальными машинами подсказки нет ни в одном из случаев.

На пробном доступе эти ранние подсказки используют ту же предварительную оценку, что и GET /v1/me. Подходящий по сохранённому состоянию хост даёт рекомендацию попробовать одношаговый запрос. При отсутствии хоста двухшаговый путь разрешён, только когда capabilities.servers.create.available равен true. Если существующий хост непригоден, для нового one-shot запроса нужно дождаться восстановления, починить хост либо повысить тариф; после удаления хоста следует заново прочитать GET /v1/me и перейти на объявленный там двухшаговый путь. Подсказка носит рекомендательный характер: окончательное решение принимает POST.

Если запрос с source уже дошёл до фактической проверки и вернул SOURCE_AT_CREATE_GALAXY_ONLY, его error.hint учитывает результат этой проверки. При существующем хосте на пробном доступе подсказка запрещает двухшаговый путь, когда capabilities.servers.create.available равен false: при включённом контроле trial-ограничений он вернёт 402 TRIAL_PORTAL_LIMIT. При отсутствии хоста она разрешает создать отдельную машину без 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 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
      }
    }
  }
}

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

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

POST /v1/infra/servers не создаёт второй сервер и возвращает существующий в двух случаях. Первый — ключ вызова принадлежит карточке из раздела «Приложения», к которой уже привязан живой сервер. Второй — тот же API-ключ уже создаёт GALAXY_APP в статусе provisioning, у сервера есть живая keyless-карточка, раздел «Приложения» виден порталу, а родительский Galaxy-host по-прежнему жив: не удалён, имеет тип GALAXY и не находится в error/deleted. Второй случай действует при любом размещении, кроме placement: "dedicated", даже если после первого запроса настройки размещения переключились на отдельные машины, и проверяется до fresh-only отказа для тела с source. После выхода такого приложения из provisioning следующий create снова может создать новый сервер.

Имя, которое вы передали в 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. При схождении на keyless-приложении в provisioning этот запрос никогда не запускает вторую сборку и отвечает sourceIgnored: true. Если ранняя сборка уже идёт, data.next отсутствует: не вызывайте deploy параллельно, дождитесь выхода сервера из provisioning и только потом разворачивайте проигнорированный source через POST /v1/infra/servers/:id/deploy, если замена всё ещё нужна. Для припаркованного приложения без активной сборки ответ сохраняет next: "deploy".

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

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

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

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

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

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

Повтор возможен в течение 15 минут с момента резервирования ключа (для прежних standalone-записей — создания сервера). После этого окна тот же ключ сервер уже не вернёт: запрос пройдёт как новое создание со всеми проверками прав — и либо получит обычный отказ по правам (402 / 403), либо 409 IDEMPOTENCY_KEY_ALREADY_USED. Если сервер не удаляли, он никуда не делся — текст ответа это скажет.

Важно: повторяйте ТЕМ ЖЕ ключом, а не новым. Для standalone-создания тот же Idempotency-Key вторую машину не создаст: он вернёт либо сам сервер, либо 409 с ответом о его судьбе. Новый Idempotency-Key сам по себе не является повтором прежнего запроса, но обычные правила переиспользования всё равно действуют. В частности, запрос тем же API-ключом при живом keyless GALAXY_APP в provisioning вернёт его с reused: true при любом недедицированном размещении. Поэтому новый ключ не означает, что обязательно будет создан новый сервер: проверяйте data.id, data.reused и GET /v1/infra/servers.

• Ключ — строка 1–255 символов из набора [A-Za-z0-9_.:-]. Область действия — ваш API-ключ.
• При повторе standalone одноразовые SSH-данные не выдаются повторно. В теле ответа ssh.privateKey и ssh.password будут null, а поле note пояснит это. Сохраняйте данные из ответа первого создания. У GALAXY_APP своих SSH-данных нет: ssh равен null, поле note не требуется.
• Galaxy-создание и переиспользование защищены после включения новой защиты. Ключ резервируется независимо от строки ресурса: несколько разных ключей могут вернуть один переиспользованный слот. Новые fresh, revived и reused результаты запоминают точный applicationId; если фоновая привязка fresh/revived-сервера находит уже созданную для этого ключа карточку, запись атомарно переключается с предварительно зарезервированного id на id именно этой карточки, после чего он фиксирован. Повтор того же ключа в течение 15 минут принимает только эту точную карточку, а не любую более позднюю карточку того же владельца на том же сервере. Платформа также заново проверяет владельца и портал обеих строк и живой Galaxy-host. Если записанная карточка была удалена, отвязана или заменена, владение изменилось либо host удалён/перешёл в error/deleted, ключ остаётся израсходованным, но ответ — 409 IDEMPOTENCY_KEY_ALREADY_USED без data и прежнего id; в новое создание запрос не проваливается. UUID-only записи до включения защиты остаются legacy. После окна действуют обычные проверки и отказ занятого ключа. До активации первое galaxy-создание по-прежнему не резервирует ключ; уже записанные ключи читаются и после выключения защиты. Старые galaxy-создания без записи ключа восстановить нельзя.
• Заголовок несовместим с graduateFrom для выделенного сервера — вернётся 400 IDEMPOTENCY_UNSUPPORTED_WITH_GRADUATION.
• Повтор записанного ключа не запускает сборку повторно. После ошибки сборки используйте явный deploy. Fresh/revived Galaxy-результат повторяется обычным create-ответом; semantic reuse снова содержит reused, reusedReason, requestedName, sourceIgnored/metaIgnored, warnings, hint и применимый next. Эти поля учитывают текущее валидированное тело повтора, но новая запись reuse отдельно помнит, принял ли исходный запрос свой source: пока начатая им сборка активна, повтор отвечает deploying: true без sourceIgnored и без next; после её завершения source также не объявляется проигнорированным и автоматически повторно не разворачивается. У прежней записи формата v1 этого признака нет, поэтому повтор не выдумывает исход: не отдаёт sourceIgnored или next, а просит сначала проверить сервер и логи и не запускать deploy автоматически. Запрос с новым ключом проходит обычные правила reuse: пустой или ошибочный слот может начать сборку, а схождение на keyless-приложении с уже активной сборкой не запускает вторую и может вернуть sourceIgnored: true.

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

• Примеры корректных и некорректных имён по паттерну ^[a-z][a-z0-9-]*$:
  • Правильно: my-app, bot-1, crm-dashboard.
  • Неправильно: My-App (заглавная), bot_1 (подчёркивание), my.app (точка), кириллица.
• Свой sshPublicKey на заранее подготовленной машине. Если первый ответ создания пришёл со статусом running и без reused: true, платформа выдала заранее подготовленную машину. Если вы передали sshPublicKey, платформа установила его до ответа: для входа по SSH используйте свой ключ или ключ из ssh.privateKey. Смотрите именно первый ответ: повтор с тем же Idempotency-Key показывает статус сервера на момент повтора.
• Когда region в ответе отличается от запрошенного. В запрошенной зоне могли кончиться IP-адреса (Address space exhausted) — тогда платформа автоматически пробует следующие зоны в порядке из GET /v1/infra/providers/:providerId/regions, и фиксирует это в аудит-логе событием SERVER_ZONE_FALLBACK.
• Таймаут провижининга — 15 минут. Если status держится в provisioning дольше, платформа переводит сервер в error и заполняет provisionError и provisionErrorCode. Дальше остаётся вызвать DELETE и создать новый.
• Новая обычная машина получает таймаут авто-сна 60 минут. Фактическое сохранённое значение приходит уже в data.sleepAfterMinutes ответа создания и затем в GET /v1/infra/servers/:id. При reuse и idempotency replay это значение существующей записи, поэтому оно может быть null или отличаться от 60. Сервер, родившийся на расписании, отмеченном для новых машин, это значение хранит, но оно не действует, пока расписание назначено, — режим виден в полях runMode и workSchedule того же GET. Входящие HTTP-запросы и активность по SSH сбрасывают таймер, а cron, фоновые процессы и собственные исходящие запросы приложения — нет. Допустимые значения и осознанное отключение авто-сна через PATCH с null — Настроить авто-сон.
• Рантайм устанавливается на этапе деплоя. Параметр runtime без source в POST /v1/infra/servers не принимается (вернёт 400 RUNTIME_PARAM_REMOVED). Указывайте runtime в теле POST /:id/deploy — для отдельной виртуальной машины начало конвейера идёт в порядке runtime → stop_existing → clean → download → install. Вместе с source рантайм принимается и обязателен: это одношаговое создание galaxy-приложения, где runtime и start идут в том же запросе.
• Кириллица в displayName и description из Windows PowerShell. Отправленная без явной сериализации в UTF-8, она сохраняется знаками вопроса (?): байты теряются на стороне клиента, до отправки запроса. Готовый вызов с UTF8.GetBytes — Windows / PowerShell и UTF-8.

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

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