Для AI-агентов: markdown этой страницы — /docs-content/applications/replace-server.md индекс документации — /llms.txt

Заменить сервер приложения

POST /v1/applications/:id/replace-server

Переносит приложение на другой сервер: на существующий сервер владельца или на новый, который метод создаёт сам. Старый сервер не удаляется. Приложение отвязывается от него, а сервер остаётся у владельца. Перед вызовом узнайте, возможна ли замена, и выберите сервер через GET /v1/applications/:id/available-servers.

Метод доступен только владельцу карточки и только его ключам. Администратор портала, который приложением не владеет, заменяет сервер в кабинете.

Авторизация: X-Api-Key со скоупом vibe:infra.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типstring Обяз.да ОписаниеИдентификатор приложения. Список: GET /v1/applications
ПараметрIdempotency-Key (header) Типstring Обяз.нет ОписаниеТолько для формы new, в форме { serverId } игнорируется. От 1 до 255 символов из A-Z, a-z, 0-9, _, ., :, -, пробелы по краям отбрасываются. Ключ действует в пределах API-ключа вызова. Как работает повтор — в «Известных особенностях»

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

Тело принимает одну из двух форм. Поля из разных форм смешивать нельзя, лишние поля дают 400 VALIDATION_ERROR.

Свой существующий сервер.

Поле Тип Обяз. Описание
ПолеserverId Типstring Обяз.да ОписаниеИдентификатор сервера из servers[].id метода GET /v1/applications/:id/available-servers

Новый сервер.

Поле Тип Обяз. Описание
Полеprovider Типstring Обяз.да ОписаниеИдентификатор провайдера, как в POST /v1/infra/servers
Полеplan Типstring Обяз.да ОписаниеИдентификатор тарифа провайдера, как в POST /v1/infra/servers
Полеregion Типstring Обяз.нет ОписаниеИдентификатор региона провайдера

Примеры

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

Terminal
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server

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

Terminal
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server

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

javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()

for (const warning of data.warnings) {
  console.warn('Нужно доделать вручную:', warning)
}

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

javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()

Новый сервер создаётся телом {"provider": "bitrix-cloud", "plan": "bc-small", "region": "ru-central1-b"}. Такой вызов платный. Чтобы повтор не создал второй сервер, передавайте заголовок Idempotency-Key, см. «Известные особенности».

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.serverId Типstring ОписаниеИдентификатор сервера, на который теперь указывает приложение
Полеdata.oldServerId Типstring | null ОписаниеИдентификатор прежнего сервера. null, если у приложения сервера не было
Полеdata.branch Типstring Описаниеexisting — перенос на свой сервер, new — создан новый сервер
Полеdata.appUrlMoved Типboolean ОписаниеПеренесён ли адрес приложения на новый сервер
Полеdata.warnings Типarray ОписаниеЧто не удалось довести до конца после переноса. Пустой массив, если всё прошло. Значения — в таблице ниже
Полеdata.callerKeyManagesServer Типboolean | null ОписаниеУправляет ли новым сервером ключ, которым сделан вызов. null, если платформа не смогла это прочитать

Значения data.warnings:

Значение Что произошло и что делать
ЗначениеKEY_ASSIGN_FAILED Что произошло и что делатьНовый сервер не удалось передать ключу приложения. Приложение указывает на новый сервер, но ключ для управления им назначен не был
ЗначениеAPP_URL_MOVE_FAILED Что произошло и что делатьАдрес приложения не перенесён на новый сервер. Перенесите его вручную
ЗначениеAPP_URL_MANUAL Что произошло и что делатьУ приложения свой адрес, платформа оставила его как есть
ЗначениеCATALOG_STALE Что произошло и что делатьУ прежнего сервера была опубликованная карточка каталога. Опубликуйте карточку заново
ЗначениеSERVER_KEY_STALE Что произошло и что делатьНа выбранном существующем сервере в окружении остался ключ приложения, который отозван или истёк. Обновите ключ в окружении сервера
ЗначениеLOGIN_SECRET_ROTATED Что произошло и что делатьУ приложения встроенный вход, а прежний сервер принадлежал другому человеку, поэтому замена сменила секрет входа. Пользователи приложения выйдут из аккаунтов, админку приложения открывают только владельцы. Настройки почты (SMTP) в админке приложения введите заново

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

JSON
{
  "success": true,
  "data": {
    "serverId": "srv_new",
    "oldServerId": "srv_old",
    "branch": "existing",
    "appUrlMoved": true,
    "warnings": [],
    "callerKeyManagesServer": true
  }
}

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

409 — сервер уже привязан к другому приложению:

JSON
{
  "success": false,
  "error": {
    "code": "SERVER_ALREADY_LINKED",
    "message": "Server is linked to another application"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодVALIDATION_ERROR ОписаниеТело не совпадает ни с { serverId }, ни с { provider, plan, region? } или содержит лишние поля
HTTP400 КодINVALID_IDEMPOTENCY_KEY ОписаниеТолько форма new: заголовок Idempotency-Key пустой, длиннее 255 символов или содержит недопустимые символы
HTTP400 КодSERVER_ALREADY_CURRENT ОписаниеСервер уже привязан к этому приложению
HTTP400 КодINVALID_PLAN ОписаниеТолько форма new: тарифа из plan нет в каталоге провайдера
HTTP400 КодINVALID_REGION ОписаниеТолько форма new: региона из region нет в каталоге провайдера
HTTP400 КодPROVIDER_DEPRECATED ОписаниеТолько форма new: провайдер выведен из работы
HTTP400 КодKEY_NOT_ELIGIBLE ОписаниеТолько форма new: ключ больше не может владеть сервером
HTTP401 КодNO_PORTAL ОписаниеКлюч не привязан к порталу
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан: такой строки на платформе нет
HTTP402 КодACCOUNT_FROZEN ОписаниеБаланс портала заморожен. Если закрыты только платные вызовы, перенос на свой существующий сервер работает, а форма new получает этот отказ с userMessage и alternatives
HTTP402 КодCOMMERCIAL_PLAN_REQUIRED ОписаниеТолько форма new: платформа не нашла запись портала, к которому привязан ключ, и не может проверить доступ
HTTP402 КодTRIAL_PORTAL_LIMIT ОписаниеТолько форма new: исчерпана квота серверов портала на пробном доступе
HTTP402 КодPLAN_NOT_ALLOWED_ON_TRIAL ОписаниеТолько форма new: тариф из plan недоступен на пробном периоде. Разрешённые тарифы — в error.details.allowedPlans
HTTP402 КодMARKETPLACE_REQUIRED ОписаниеТолько форма new: на портале нет активной подписки BitrixGPT + Маркетплейс, а доступ к платформе открывает она
HTTP402 КодKZ_PAID_ONLY ОписаниеТолько форма new: портал из региона KZ, доступ открывает платный или демо-тариф Битрикс24
HTTP402 КодUZ_PAID_ONLY ОписаниеТолько форма new: портал из региона UZ, доступ открывает платный или демо-тариф Битрикс24
HTTP402 КодBY_PAID_ONLY ОписаниеТолько форма new: портал из Беларуси, доступ открывает платный или демо-тариф Битрикс24 либо подписка Битрикс24 Маркет Плюс
HTTP402 КодINT_TARIFF_REQUIRED ОписаниеТолько форма new: аккаунт получает доступ по тарифу Битрикс24, нужен коммерческий тариф
HTTP402 КодINT_VIBE_PLUS_REQUIRED ОписаниеТолько форма new: на аккаунте Битрикс24 нужен тариф Vibe+
HTTP402 КодSELFHOSTED_NOT_AVAILABLE ОписаниеТолько форма new: коробочный Битрикс24 пока не доступен на этой установке. Покупка тарифа отказ не снимает
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения
HTTP403 КодINFRA_FORBIDDEN_FOR_COWORK_KEY ОписаниеКлюч со скоупом vibe:cowork работает только с данными
HTTP403 КодFORBIDDEN ОписаниеПриложение принадлежит не владельцу ключа
HTTP403 КодMANAGEMENT_KEY_NO_ENTITY_ACCESS ОписаниеУправляющий ключ: нужен личный ключ или ключ авторизации
HTTP403 КодPORTAL_KEY_REQUIRED ОписаниеЗапись ключа повреждена и не имеет владельца
HTTP403 КодINFRA_NOT_PERMITTED ОписаниеТолько форма new: инфраструктура отключена на платформе или на портале
HTTP403 КодSERVER_CREATION_DISABLED ОписаниеТолько форма new: создание серверов запрещено политикой портала
HTTP403 КодSERVER_CREATION_ADMINS_ONLY ОписаниеТолько форма new: политика портала разрешает создавать серверы только администраторам
HTTP403 КодVIBE_DEMO_EXPIRED ОписаниеТолько форма new: тариф Vibe+ или пробный период закончился
HTTP404 КодAPPLICATION_NOT_FOUND ОписаниеПриложения нет на портале ключа
HTTP404 КодSERVER_NOT_FOUND ОписаниеСервера нет, он чужой или к приложению его привязать нельзя: это сервер агента, бота или хост галактики
HTTP404 КодPROVIDER_NOT_FOUND ОписаниеТолько форма new: провайдер неизвестен или закрыт для этого портала
HTTP409 КодIDEMPOTENCY_KEY_ALREADY_USED ОписаниеТолько форма new: ключ Idempotency-Key уже использован с другим приложением или телом, приложение с тех пор перенесено на другой сервер, либо исход прежнего вызова неизвестен
HTTP409 КодIDEMPOTENCY_CONCURRENT_RETRY ОписаниеТолько форма new: параллельный запрос занял тот же ключ Idempotency-Key
HTTP409 КодSERVER_ALREADY_LINKED ОписаниеСервер привязан к другому приложению
HTTP409 КодAPPLICATION_OP_IN_PROGRESS ОписаниеПривязку сервера к приложению меняет другая операция, либо она изменилась во время запроса. Повторите позже
HTTP409 КодREISSUE_IN_PROGRESS ОписаниеКлюч приложения или его привязка к серверу заняты перевыпуском ключа, доставкой секретов или удалением. Повторите позже
HTTP409 КодAPPLICATION_KEY_RECOVERY_REQUIRED ОписаниеНезавершённая замена ключа блокирует перенос. Завершите или восстановите её
HTTP409 КодPORTAL_ORIGIN_CUTOVER_BUSY ОписаниеАдрес портала меняет другая операция, повторите позже
HTTP409 КодAPPLICATION_MOVE_ACTIVE ОписаниеПриложение переезжает на новый сервер. В теле — moveId, status и retryAfter (секунды), тот же срок в заголовке Retry-After. Не создавайте новый сервер: подождите и повторите
HTTP409 КодAPPLICATION_MOVE_RETAINING ОписаниеПосле переезда прежний сервер хранится для возврата до keepOldUntil. Сначала удалите прежний сервер или дождитесь срока
HTTP409 КодAPP_LOGIN_SDK_NOT_CONFIRMED ОписаниеПриложение со встроенным входом, прежний сервер принадлежит другому человеку, а приложение переведено со входа 0.3 и запуск на SDK 0.4 не подтверждён. Ничего не изменилось. Переведите приложение на SDK 0.4 и повторите
HTTP429 КодRATE_LIMITED Описание10 запросов в минуту на владельца карточки, каким бы ключом он ни вызывал
HTTP429 КодSERVER_LIMIT ОписаниеТолько форма new: достигнут лимит серверов на ключ
HTTP429 КодUSER_SERVER_LIMIT ОписаниеТолько форма new: достигнут лимит серверов на человека
HTTP502 КодAPPLICATION_SERVER_ATTACH_FAILED ОписаниеНовый сервер создан, но привязать его не удалось. Сервер удалён, приложение осталось на старом
HTTP502 КодPROVIDER_ERROR ОписаниеТолько форма new: сбой обращения к облачному провайдеру. В ответе приходит error.incidentCode, назовите его поддержке
HTTP502 КодPROVIDER_NOT_CONFIGURED ОписаниеТолько форма new: провайдер не настроен на платформе — у него нет учётных данных или цены для выбранного тарифа. В ответе приходит error.incidentCode
HTTP503 КодPORTAL_ORIGIN_CUTOVER_UNAVAILABLE ОписаниеЗащита адреса портала недоступна, повторите позже

Текст error.message английский и предназначен для журналов: тексты для интерфейса стройте по error.code. Полный список общих ошибок API — Ошибки.

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

  • Сбой после записи связи не превращается в ошибку. Как только приложение указывает на новый сервер, метод отвечает 200, а то, что довести не удалось, перечисляет в warnings. Ошибкой ответа бывает только то, что случилось до записи связи. Клиент, который смотрит лишь на статус ответа, пропустит предупреждения: читайте warnings всегда.
  • Повтор формы new с Idempotency-Key. Повтор с тем же ключом и тем же телом в течение 24 часов после первого вызова второй сервер не создаёт. Если замена завершилась, ответ 200 повторяет прежние data.serverId, data.oldServerId и data.appUrlMoved с пустым data.warnings и несёт заголовок Idempotent-Replayed: true. Если исход неизвестен или приложение уже перенесено на другой сервер, приходит 409 IDEMPOTENCY_KEY_ALREADY_USED. Тогда прочитайте GET /v1/applications/:id, где server.id — текущий сервер приложения, и проверьте в кабинете, не появился ли отвязанный сервер, прежде чем повторять покупку. Через 24 часа защита от повтора может пропасть. Без заголовка повтор может создать второй сервер.
  • Ключ вызова не переназначается. Управляющий ключ нового сервера — собственный ключ приложения: ключ авторизации, если он есть, иначе личный ключ. Ключ, которым вы сделали вызов, остаётся прежним. Управляет ли он новым сервером, говорит callerKeyManagesServer. Это false, когда у приложения есть ключ авторизации или целевой сервер — контейнер галактики.
  • Сервер создаётся за владельцем карточки. Лимиты и платёжные условия применяются к нему, а не к администратору портала.
  • Старый сервер остаётся. Он отвязан от приложения и работает у владельца. Если он вам не нужен, удалите его отдельно через DELETE /v1/infra/servers/:id.
  • Приложение со встроенным входом и чужой прежний сервер. Если прежний сервер принадлежит не владельцу карточки, замена вместе с переносом меняет секрет входа: секрет в окружении прежнего сервера перестаёт действовать. Сессии пользователей приложения завершаются, а админка входа открыта только его владельцам: администраторы без отметки владельца в неё не попадают. База входа на диске прежнего сервера и в его резервных копиях остаётся. О смене говорит значение LOGIN_SECRET_ROTATED в data.warnings. Если прежний сервер ваш, секрет не меняется.
  • Показывать кнопку или нет, решает available-servers. Он же заранее называет причину отказа для формы new. Остальные причины приходят кодами ошибок из таблицы выше.

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