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

Серверы для переноса приложения

GET /v1/applications/:id/available-servers

Показывает, куда владелец может перенести приложение: на какие из своих серверов и можно ли создать новый. Вызовите метод до того, как покажете экран замены сервера. По ответу видно, нужна ли кнопка замены, а если замена недоступна, причина приходит кодом. Саму замену делает POST /v1/applications/:id/replace-server.

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

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

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типstring Обяз.да ОписаниеИдентификатор приложения. Список: GET /v1/applications

Примеры

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

Terminal
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/available-servers

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

Terminal
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/available-servers

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

javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/available-servers`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()

console.log('Свои серверы:', data.servers.map((s) => s.name))
if (!data.canCreateNew) {
  console.log('Новый сервер недоступен:', data.createNewBlocked.code)
}

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

javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/available-servers`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеКуда можно перенести приложение
Полеdata.servers Типarray ОписаниеСерверы владельца, на которые можно перенести приложение. Не больше 50, сначала новые. Может быть пустым
Полеdata.servers[].id Типstring ОписаниеИдентификатор сервера. Передайте его как serverId в POST /v1/applications/:id/replace-server
Полеdata.servers[].name Типstring ОписаниеИмя сервера
Полеdata.servers[].displayName Типstring | null ОписаниеОтображаемое имя, если задано
Полеdata.servers[].status Типstring ОписаниеСостояние сервера строчными буквами, как в GET /v1/infra/servers
Полеdata.servers[].providerId Типstring ОписаниеПровайдер сервера
Полеdata.servers[].plan Типstring ОписаниеТариф сервера
Полеdata.servers[].region Типstring ОписаниеРегион сервера
Полеdata.servers[].kind Типstring ОписаниеSTANDALONE — отдельная машина, GALAXY_APP — контейнер приложения в галактике
Полеdata.servers[].blackholeStatus Типstring | null ОписаниеСостояние туннеля сервера
Полеdata.servers[].createdAt Типstring ОписаниеВремя создания сервера, ISO 8601
Полеdata.canCreateNew Типboolean ОписаниеМожно ли сейчас заменить сервер новым, создав его
Полеdata.createNewBlocked Типobject ОписаниеПриходит только при canCreateNew: false и называет причину
Полеdata.createNewBlocked.code Типstring ОписаниеACCOUNT_FROZEN, INFRA_NOT_PERMITTED, SERVER_CREATION_DISABLED или SERVER_CREATION_ADMINS_ONLY
Полеdata.createNewBlocked.message Типstring ОписаниеТекст для журнала, английский
Полеdata.createNewBlocked.userMessage Типstring ОписаниеТекст для человека на языке владельца ключа
Полеdata.createNewBlocked.alternatives Типarray ОписаниеЧто можно сделать вместо создания. Форма совпадает с 402 у POST /v1/applications/:id/replace-server

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

JSON
{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "srv_new",
        "name": "my-server",
        "displayName": null,
        "status": "running",
        "providerId": "bitrix-cloud",
        "plan": "bc-small",
        "region": "ru-central1-b",
        "kind": "STANDALONE",
        "blackholeStatus": null,
        "createdAt": "2026-10-01T09:00:00.000Z"
      }
    ],
    "canCreateNew": true
  }
}

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

403 — приложение принадлежит другому человеку, администратор портала заменяет сервер в кабинете:

JSON
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Forbidden"
  }
}

Ошибки

HTTP Код Описание
HTTP401 КодNO_PORTAL ОписаниеКлюч не привязан к порталу
HTTP401 КодMISSING_API_KEY, INVALID_API_KEY ОписаниеНет действительного ключа
HTTP402 КодACCOUNT_FROZEN ОписаниеБаланс портала заморожен и весь раздел /v1 закрыт. В теле message и topupUrl. Если закрыты только платные вызовы, метод отвечает 200 с canCreateNew: false
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодINFRA_FORBIDDEN_FOR_COWORK_KEY ОписаниеКлюч со скоупом vibe:cowork работает только с данными, метод ему закрыт, в том числе на чтение
HTTP403 КодFORBIDDEN ОписаниеПриложение принадлежит не владельцу ключа
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения
HTTP403 КодMANAGEMENT_KEY_NO_ENTITY_ACCESS ОписаниеУправляющий ключ: нужен личный ключ или ключ авторизации
HTTP403 КодPORTAL_KEY_REQUIRED ОписаниеЗапись ключа повреждена и не имеет владельца. Обычный ключ без портала получает 401 NO_PORTAL выше
HTTP404 КодAPPLICATION_NOT_FOUND ОписаниеПриложения нет на портале ключа. Тот же ответ приходит на приложение чужого портала
HTTP429 КодRATE_LIMITED Описание60 запросов в минуту на владельца карточки, каким бы ключом он ни вызывал

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

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

  • В список попадает не любой сервер владельца. Сервер должен принадлежать владельцу карточки, существовать, не быть текущим сервером приложения, не быть привязан к другому приложению, не быть сервером агента или бота и не быть хостом галактики. Сервер, которого здесь нет, замена не примет: POST /v1/applications/:id/replace-server ответит на него 404 SERVER_NOT_FOUND или 409 SERVER_ALREADY_LINKED.
  • Пустой servers не мешает замене. Заменить сервер можно и созданием нового, если canCreateNew равен true. Кнопку замены прячьте, когда список пуст и canCreateNew равен false, а причину берите из createNewBlocked.
  • Заморозка баланса закрывает только создание. При ACCOUNT_FROZEN в createNewBlocked перенос на свой существующий сервер остаётся доступным, а servers заполнен по тем же правилам.
  • Правило создания зависит от политики портала. Коды INFRA_NOT_PERMITTED, SERVER_CREATION_DISABLED и SERVER_CREATION_ADMINS_ONLY значат, что политика портала не даёт этому человеку создавать серверы. Те же коды вернёт замена по форме new.
  • Ответ — снимок на момент вызова. Между этим методом и заменой сервер могут занять или удалить. Замена перепроверяет всё сама и ответит нужным кодом.
  • Метод ничего не меняет и не создаёт. Вызывать его можно столько раз, сколько нужно экрану.

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