Создать приложение из Cowork/Code

POST /v1/cowork/applications

Создаёт личное приложение и выписывает его ключ, который возвращается ровно один раз. Сервер при этом не создаётся: у личного приложения его нет по определению — сервер появляется от вашего деплоя и сам привязывается к карточке. Заголовок Idempotency-Key обязателен.

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

Значения для полей запроса берите из параметров создания приложения — там же лежат наборы прав и режим доступа, который аккаунт назначает новым ключам.

Параметры

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

Схема строгая: лишнее поле в теле отвечает 400 VALIDATION_ERROR и называет его. Размер тела ограничен 64 КБ.

Примеры

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

curl — ключ Cowork/Code

curl -X POST https://vibecode.bitrix24.tech/v1/cowork/applications \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Idempotency-Key: create-app-2026-08-25-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Отчёт по сделкам",
    "type": "personal",
    "b24Scopes": ["crm"]
  }'

JavaScript — ключ Cowork/Code

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/applications', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Idempotency-Key': 'create-app-2026-08-25-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Отчёт по сделкам',
    type: 'personal',
    b24Scopes: ['crm'],
  }),
})

if (!res.ok) {
  const { error } = await res.json()
  throw new Error(`${res.status} ${error.code}`)
}

const { data } = await res.json()

// Сырой ключ приходит один раз — сохраните его сразу
if (data.rawApiKey === null) {
  // Это повтор запроса: приложение уже создано, ключ заново не выдаётся
} else {
  saveKey(data.rawApiKey, data.keyExpiresAt)
}

Поля ответа

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

{
  "success": true,
  "data": {
    "application": {
      "id": "cmt8ht5u40005ensk4fp45ebx",
      "name": "Отчёт по сделкам",
      "description": null,
      "type": "PERSONAL",
      "iconUrl": null,
      "createdAt": "2026-08-25T09:59:01.324Z",
      "updatedAt": "2026-08-25T09:59:01.324Z",
      "viewerState": "owner",
      "pinned": false,
      "author": { "name": "Роман Глушаков" },
      "isEmbedded": false,
      "openUrl": null,
      "openTarget": null,
      "server": null,
      "sources": { "hasVersions": false, "latestVersionId": null, "latestSavedAt": null },
      "activeOperation": null
    },
    "applicationId": "cmt8ht5u40005ensk4fp45ebx",
    "rawApiKey": "vibe_api_ge5crx6rXOgoFikYi7G2inWA6dx7VO1V_9bcf92",
    "keyExpiresAt": null,
    "mode": "READWRITE",
    "warnings": [],
    "warningCodes": []
  }
}

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

409 — квота ключей исчерпана:

{
  "success": false,
  "error": {
    "code": "KEY_LIMIT_REACHED",
    "message": "Maximum number of API keys reached",
    "details": { "used": 40, "limit": 40, "requested": 1, "scope": "portal" }
  }
}

Удаление выданного ключа в кабинете НЕ отменяет идемпотентность: карточка остаётся, а повтор с тем же ключом идемпотентности по-прежнему отвечает 201 с заголовком Idempotent-Replayed: true и warningCodes: ["KEY_NOT_REPLAYABLE"]. Нового ключа этот повтор не выпишет — сырой ключ отдаётся ровно один раз, при первом создании; получить рабочий ключ для существующего приложения можно через POST /v1/keys/:id/rotate.

Ошибки

Перечень отказов самого эндпоинта исчерпывающий: кода, которого здесь нет, эндпоинт не отдаёт. Выписка ключа идёт через Битрикс24 Нетворк, и его отказы переподнимаются дословно — они в таблице тоже. У коробочного аккаунта выписка идёт своим каналом и приносит собственные коды, разобранные в Ключах и авторизации. Форма ответа та же, ветвитесь по error.code.

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

Идемпотентность

Заголовок Idempotency-Key обязателен, и это отличие от создания сервера, где он необязателен. Причина в том, что эндпоинт выписывает ключ и занимает место в квоте: без защиты обрыв сети оставлял бы второе приложение и второй ключ.

Повтор запроса с тем же ключом и тем же телом отвечает 201, добавляет заголовок ответа Idempotent-Replayed: true и возвращает ту же карточку. Сырой ключ при этом приходит null, а в warningCodes появляется KEY_NOT_REPLAYABLE: у платформы лежит только хеш ключа, восстановить сам ключ нечем.

Потерянный ключ повтором не возвращается, и перевыпустить его этим ключом Cowork/Code нельзя — идентификатора выданного ключа в ответе нет, а раздел /v1/keys принимает только управляющий ключ. Практический путь один: создайте приложение заново с НОВЫМ значением Idempotency-Key и получите свежий ключ, а лишнюю карточку и её ключ уберите в кабинете платформы. Поэтому сохраняйте rawApiKey сразу, в том же обработчике ответа.

Отпечаток снимается с приведённого к общему виду тела: порядок полей и порядок значений внутри b24Scopes на сравнение не влияют, поэтому переставленные местами поля по-прежнему считаются тем же запросом. Пробелы по краям name тоже не влияют, а expiresInDays: null и отсутствие этого поля считаются одним и тем же. Другое тело с тем же ключом отвечает 409 IDEMPOTENCY_KEY_BODY_MISMATCH, а не отдаёт чужой результат.

Повторяйте то же тело, а не уточнённое. Опущенное необязательное поле и то же поле со значением, которое аккаунт подставил бы сам, дают РАЗНЫЕ отпечатки: если первый запрос шёл без mode, а повтор дописал mode, придёт 409 IDEMPOTENCY_KEY_BODY_MISMATCH. По той же причине различаются ["crm"] и ["crm", "crm"] — набор прав перед сравнением сортируется, но дубликаты из него не убираются.

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

Срок жизни ключа по умолчанию не применяется — поле keyExpiresInDays из параметров создания это подсказка, а не значение по умолчанию. Если не передать expiresInDays, ключ выписывается бессрочным, и в ответе keyExpiresAt приходит null. Хотите ограничить срок — передайте число дней явно, а показать человеку можно значение из параметров создания.

Права placement, entity и userfieldtype на выписанном ключе не окажутся. В смешанном наборе они отбрасываются без отказа: личный ключ их не исполняет. Отказ приходит только тогда, когда кроме них в b24Scopes не передано ничего. Состав прав проверяйте по выданному ключу, а не по отправленному запросу.

Выписанный ключ не умеет обращаться к искусственному интеллекту и веб-поиску. Он несёт vibe:infra, vibe:storage и запрошенные права Битрикс24, а vibe:ai и vibe:search в него не попадают ни в строке прав, ни в правах во время работы. Приложение, созданное так, не сможет расходовать кошелёк аккаунта на модели и поиск.

Порядок отказов несущий: сначала права вызывающего ключа, потом состояние продукта, потом стоимость. Проверки идут так: сначала сам ключ — существование, срок, режим «только чтение», заморозка баланса. Затем скоуп vibe:cowork, класс ключа, отключение всего Cowork/Code, активность подписки, отключение самого мастера. Затем идемпотентность и схема тела. И только потом доступ аккаунта к платформе, политика создания приложений и квота ключей. Если нарушено несколько условий сразу, придёт первый отказ из этой цепочки.

Отказ 500 APPLICATION_CREATE_FAILED означает, что ключ уже выписан. Место в квоте занято, а карточки нет. Повторяйте с новым ключом идемпотентности, а лишний ключ отзовите — отзыв освобождает место в квоте, удалять ключ не обязательно.

Часть полей карточки эта ручка не наполняет — читайте их из витрины. Набор полей совпадает с GET /v1/applications/:id, но pinned здесь всегда false, а sources и activeOperation всегда пустые, даже если приложение уже задеплоено и человек закрепил его в кабинете. За этими признаками обращайтесь к витрине приложений, а из ответа создания берите идентификатор, имя и ключ.

Сервер к карточке привязывается сам. После создания приложения поднимайте сервер своим POST /v1/infra/servers с параметрами из блока server параметров создания. Отдельного вызова, связывающего сервер с карточкой, нет и не нужно.

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

• Параметры создания приложения
• Создать сервер
• Карточка приложения
• Ключи и авторизация
• Cowork/Code
• Ошибки