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

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

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

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

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

## Параметры

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

## Примеры

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

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

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

```bash
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`](./replace-server.md) |
| `data.servers[].name` | string | Имя сервера |
| `data.servers[].displayName` | string \| null | Отображаемое имя, если задано |
| `data.servers[].status` | string | Состояние сервера строчными буквами, как в [`GET /v1/infra/servers`](/docs/infra/servers/list) |
| `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`](./replace-server.md) |

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

```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 | Код | Описание |
|------|-----|---------|
| 401 | `NO_PORTAL` | Ключ не привязан к порталу |
| 401 | `MISSING_API_KEY`, `INVALID_API_KEY` | Нет действительного ключа |
| 402 | `ACCOUNT_FROZEN` | Баланс портала заморожен и весь раздел `/v1` закрыт. В теле `message` и `topupUrl`. Если закрыты только платные вызовы, метод отвечает `200` с `canCreateNew: false` |
| 403 | `INFRA_SCOPE_REQUIRED` | У ключа нет скоупа `vibe:infra` |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Ключ со скоупом `vibe:cowork` работает только с данными, метод ему закрыт, в том числе на чтение |
| 403 | `FORBIDDEN` | Приложение принадлежит не владельцу ключа |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | Управляющий ключ: нужен личный ключ или ключ авторизации |
| 403 | `PORTAL_KEY_REQUIRED` | Запись ключа повреждена и не имеет владельца. Обычный ключ без портала получает `401 NO_PORTAL` выше |
| 404 | `APPLICATION_NOT_FOUND` | Приложения нет на портале ключа. Тот же ответ приходит на приложение чужого портала |
| 429 | `RATE_LIMITED` | 60 запросов в минуту на владельца карточки, каким бы ключом он ни вызывал |

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

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

- **В список попадает не любой сервер владельца.** Сервер должен принадлежать владельцу карточки, существовать, не быть текущим сервером приложения, не быть привязан к другому приложению, не быть сервером агента или бота и не быть хостом галактики. Сервер, которого здесь нет, замена не примет: `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`.
- **Ответ — снимок на момент вызова.** Между этим методом и заменой сервер могут занять или удалить. Замена перепроверяет всё сама и ответит нужным кодом.
- **Метод ничего не меняет и не создаёт.** Вызывать его можно столько раз, сколько нужно экрану.

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

- [Заменить сервер приложения](./replace-server.md)
- [Карточка приложения](./get.md)
- [Список серверов](/docs/infra/servers/list)
- [Витрина приложений](/docs/applications)
- [Ошибки](/docs/errors)
