## Параметры создания приложения

`GET /v1/cowork/applications/defaults`

Возвращает всё, что мастеру создания приложения нужно узнать до первого вопроса человеку: наборы прав на выбор, режим доступа будущего ключа, остаток квоты ключей и параметры сервера. Читающий эндпоинт без побочных эффектов — ни приложения, ни ключа он не создаёт, поэтому его можно звать при каждом открытии мастера и перед деплоем, чтобы подтвердить цену.

**Скоуп:** `vibe:cowork` (ключ Cowork/Code) | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

Блок `server` описывает параметры, которые вы передадите в свой [`POST /v1/infra/servers`](/docs/infra/servers/create). Значения из него идут туда **дословно** — преобразовывать их не нужно.

## Примеры

Эндпоинт принимает только ключ Cowork/Code, поэтому примеров два: ключ без скоупа `vibe:cowork` получает `403 INSUFFICIENT_SCOPE`.

### curl — ключ Cowork/Code

```bash
curl https://vibecode.bitrix24.tech/v1/cowork/applications/defaults \
  -H "X-Api-Key: YOUR_COWORK_KEY"
```

### JavaScript — ключ Cowork/Code

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/applications/defaults', {
  headers: { 'X-Api-Key': 'YOUR_COWORK_KEY' },
})
const { data } = await res.json()

if (!data.available) {
  // Создание приложений отключено — пункт мастера лучше скрыть заранее
  return
}

// Наборы прав рисуем по стабильному id, подписи берём из своих словарей
const presets = data.scopePresets.map(p => ({ id: p.id, scopes: p.b24Scopes }))

// Цену показываем, только когда она пришла
const priceKnown = data.server.priceMonthly !== null
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.available` | boolean | `false` — создание приложений выключено на уровне платформы. Скройте пункт мастера: `POST /v1/cowork/applications` ответит `503 APP_CREATE_DISABLED`. Остальные поля приходят полностью и при `false` |
| `data.scopePresets` | array | Наборы прав для шага «какие данные портала нужны приложению» |
| `data.scopePresets[].id` | string | Стабильный идентификатор набора — `crm`, `tasks`, `people`. По нему подставляйте свою подпись: платформа подписей не отдаёт |
| `data.scopePresets[].b24Scopes` | array | Права Битрикс24, которые запрашивает набор. Непустой всегда. Эти значения передаются в поле `b24Scopes` при [создании приложения](./applications-create.md) |
| `data.mode` | string | Режим доступа, который аккаунт назначает новым ключам — `READONLY` или `READWRITE`. Покажите его: на аккаунте с `READONLY` приложение, пишущее в CRM, откажет уже после публикации |
| `data.keyExpiresInDays` | number | Срок жизни нового ключа в днях по политике аккаунта |
| `data.quota.keysUsed` | number | Сколько мест квоты ключей занято сейчас |
| `data.quota.keysLimit` | number | Пользовательская квота ключей, которую разрешил администратор аккаунта. Те же значения приходят в `details` отказа `409 KEY_LIMIT_REACHED`, когда сработал лимит пользователя. Если при создании приложения приходит `details.scope: "portal"`, отказ вызвал отдельный портальный потолок платформы, а не это поле |
| `data.server.placement` | string | Куда встанет будущий сервер — `galaxy`, `galaxy-preferred` или `standalone`. Значения разобраны в «Известных особенностях» |
| `data.server.serverWillLink` | boolean | Привяжется ли созданный вами сервер к карточке этого приложения. Поле отдаётся отдельно, чтобы вам не выводить это из `placement` |
| `data.server.provider` | string \| null | Идентификатор провайдера для поля `provider` при создании сервера. Список: [`GET /v1/infra/providers`](/docs/infra/providers/list) |
| `data.server.plan` | string \| null | Идентификатор тарифа для поля `plan`. Список: [`GET /v1/infra/providers/:providerId/plans`](/docs/infra/providers/plans) |
| `data.server.region` | string \| null | Идентификатор региона для поля `region`. Список: [`GET /v1/infra/providers/:providerId/regions`](/docs/infra/providers/regions) |
| `data.server.priceMonthly` | number \| null | Стоимость сервера за месяц в единицах `currency`. `null` означает «цена не прочитана», а не «бесплатно» |
| `data.server.currency` | string \| null | Единица измерения цены |
| `data.warningCodes` | array | Коды предупреждений. Единственный код — `SERVER_DEFAULTS_UNAVAILABLE`: каталог провайдера прочитать не удалось, поэтому тариф и цена отсутствуют. Поля `placement` и `serverWillLink` остаются достоверными, они считаются из политики аккаунта |

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

```json
{
  "success": true,
  "data": {
    "available": true,
    "scopePresets": [
      { "id": "crm", "b24Scopes": ["crm"] },
      { "id": "tasks", "b24Scopes": ["task", "tasks"] },
      { "id": "people", "b24Scopes": ["user_brief", "department"] }
    ],
    "mode": "READWRITE",
    "keyExpiresInDays": 90,
    "quota": { "keysUsed": 1, "keysLimit": 10 },
    "server": {
      "placement": "standalone",
      "serverWillLink": true,
      "provider": "bitrix-cloud",
      "plan": "bc-micro",
      "region": "ru-central1-b",
      "priceMonthly": 600,
      "currency": "Vibes"
    },
    "warningCodes": []
  }
}
```

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

403 — нет активной подписки Cowork/Code:

```json
{
  "success": false,
  "error": {
    "code": "COWORK_NOT_ACTIVATED",
    "message": "No active Cowork/Code subscription for this user+portal — an application cannot be created."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 401 | `KEY_INACTIVE` | Ключ выключен |
| 401 | `KEY_EXPIRED` | Срок действия ключа истёк |
| 402 | `ACCOUNT_FROZEN` | Баланс аккаунта исчерпан — пополните счёт. Отказ приходит и на этот читающий эндпоинт: из-под заморозки он не выведен |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 403 | `COWORK_HARNESS_KEY_FORBIDDEN` | Вызов сделан ключом стороннего агента, выписанным на подписку. Мастер создания приложений такому ключу недоступен — см. [Свой агент на подписке](/docs/cowork/harness) |
| 403 | `COWORK_NOT_ACTIVATED` | Нет активной подписки Cowork/Code для пары сотрудник и аккаунт |
| 429 | `RATE_LIMITED` | Суммарный лимит платформы — 30 запросов в минуту. Действующее для вашего ключа значение приходит в заголовке `x-ratelimit-limit` — оно ниже суммарного, поскольку лимит делится между репликами |
| 429 | `QUOTA_EXCEEDED` | Исчерпана суточная бесплатная квота вызовов при нулевом балансе на предоплате |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code отключён на уровне платформы. Отключение самого мастера сюда НЕ попадает — оно приходит полем `available: false` со статусом `200` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Три значения `placement`, а не два.** `standalone` — сервер поднимается отдельной виртуальной машиной, она тарифицируется, и цена в блоке `server` относится именно к ней. `galaxy` — сервер обязан встать контейнером внутри общего хоста. `galaxy-preferred` — контейнер предпочтителен, но при невозможности деплой уходит на отдельную машину. На контейнерном размещении деплой даёт приложение, которое запускается только после первой публикации, поэтому текст после создания говорит «создано, теперь опубликуйте», а не «сервер запускается».

**Пустая цена без предупреждения — нормальный ответ на контейнерном размещении.** `SERVER_DEFAULTS_UNAVAILABLE` появляется только при `placement: "standalone"`. При `galaxy` и `galaxy-preferred` поля `plan`, `region`, `priceMonthly` и `currency` могут прийти пустыми, а `warningCodes` останется пустым массивом: отдельная машина там не создаётся, и тарифицировать нечего. Поэтому решение «показывать цену» принимайте по самому `priceMonthly`, а не по наличию предупреждения.

**Поля блока `server` пустеют не все сразу.** `provider` определяется раньше, чем читается каталог тарифов, поэтому встречается ответ, где `provider` заполнен, а `plan`, `region`, `priceMonthly` и `currency` пусты. Проверяйте каждое поле, которое подставляете в создание сервера, а не одно из них как признак остальных.

**Поле `image` в блоке `server` отсутствует намеренно — его не нужно передавать.** При создании сервера платформа сама подбирает свежий образ операционной системы, если поле не задано. Отдельный запрос к каталогу образов ради этого не нужен, и проверка «каталог неполон» на стороне клиента здесь не требуется.

**Значения блока `server` идут в создание сервера дословно.** Преобразования между этим ответом и [`POST /v1/infra/servers`](/docs/infra/servers/create) нет: `provider`, `plan` и `region` принимаются в том же виде, в каком пришли.

**Ключ десктопа Cowork/Code место в квоте не занимает.** В `quota.keysUsed` идут личные ключи сотрудника и ключи приложений на этом аккаунте, а также ключи агентов и проектные ключи деплоя. Отозванный ключ место освобождает — удалять его не обязательно, достаточно отозвать.

**Поля предупреждений у двух ручек разные, и это не опечатка.** Здесь приходит только `warningCodes`, поля `warnings` в ответе нет вовсе, а у [создания приложения](./applications-create.md) есть оба. Один тип под оба ответа не подойдёт.

**Состав наборов прав может пополняться.** Рисуйте только те `id`, которые знаете, а незнакомые пропускайте: иначе новый набор появится в интерфейсе строкой без подписи. Состав `b24Scopes` внутри набора мы можем менять, а `id` — нет, он часть контракта.

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

- [Создать приложение из Cowork/Code](./applications-create.md)
- [Создать сервер](/docs/infra/servers/create)
- [Тарифы провайдера](/docs/infra/providers/plans)
- [Витрина приложений](/docs/applications)
- [Cowork/Code](/docs/cowork)
- [Ошибки](/docs/errors)