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

GET /v1/cowork/applications/defaults

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

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

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

Примеры

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

curl — ключ Cowork/Code

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

JavaScript — ключ Cowork/Code

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": 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:

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

Ошибки

Полный список общих ошибок API — Ошибки.

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

Три значения 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 нет: provider, plan и region принимаются в том же виде, в каком пришли.

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

Поля предупреждений у двух ручек разные, и это не опечатка. Здесь приходит только warningCodes, поля warnings в ответе нет вовсе, а у создания приложения есть оба. Один тип под оба ответа не подойдёт.

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

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

• Создать приложение из Cowork/Code
• Создать сервер
• Тарифы провайдера
• Витрина приложений
• Cowork/Code
• Ошибки