Создать приложение из 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, поэтому примеров два. У личного ключа и ключа OAuth-приложения нет скоупа 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_…",
    "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, реплеится так же — см. «Повтор после отказа».

Ошибки

Перечень отказов самого эндпоинта исчерпывающий: кода, которого здесь нет, эндпоинт не отдаёт. Выписка ключа идёт через Битрикс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"] — набор прав перед сравнением сортируется, но дубликаты из него не убираются.

Повтор после отказа

Если первая попытка отказала УЖЕ ПОСЛЕ обращения к Битрикс24 (коннектор недоступен, портал отказал, внутренняя ошибка записи), платформа хранит этот исход и в течение 20 минут отдаёт его дословно на повтор с тем же Idempotency-Key: тот же HTTP-статус, тот же error.code, то же тело, плюс заголовок Idempotent-Replayed: true. Ответ платформы неотличим от первого отказа, кроме этого заголовка — ориентируйтесь на него, если хотите отличить повтор от первой попытки.

Спустя 20 минут исход забывается: платформа освобождает ключ идемпотентности физически, и повтор с ним выполняется как совершенно новая попытка — со всеми проверками заново, включая шанс на успех. Тело повтора при этом обязано совпадать с телом первой попытки — иначе, как и всегда, придёт 409 IDEMPOTENCY_KEY_BODY_MISMATCH; исключение — если исход уже забыт (20 минут прошли), тогда сравнения тела с забытым отказом не происходит вовсе, и повтор с ЛЮБЫМ телом стартует как новая попытка.

Если первый отказ произошёл уже ПОСЛЕ обращения к Битрикс24 (например, 502 BITRIX_UNAVAILABLE), аккаунт мог уже получить вебхук от первой попытки — повтор спустя 20 минут этого не проверяет и может выписать ВТОРОЙ ключ поверх первого. Смена значения Idempotency-Key защиты здесь не даёт — что старым, что новым ключом повтор спустя окно одинаково запускает новую попытку. Как правило, на платформе при этом нечего проверить: неудавшаяся заявка на бронь удаляется вместе с исходом отказа, а ключ на большинстве стадий отказа не чеканится вовсе — возможный дубль в этом случае ищите в самом портале Битрикс24, если это возможно, и считайте риск частью цены повтора спустя окно. Исключение — 500 APPLICATION_CREATE_FAILED: там ключ иногда УЖЕ выписан (см. таблицу ошибок выше), и тогда лишний ключ можно найти и отозвать в разделе ключей кабинета платформы.

Отказ проверок, которые идут ДО того, как ключ идемпотентности занят (не прошла валидация тела, квота ключей исчерпана, портал не привязан к Нетворку, не пройдена проверка подписки или тарифа самой платформы), в эту гарантию не входит: ключ в этом случае не удерживается, и повтор с ним для платформы неотличим от первого запроса. Большинство отказов по подписке или тарифу приходит до того, как ключ занят, и не повторяется, но отказ, который портал Битрикс24 вернул уже при выписке ключа, сохраняется и повторяется 20 минут. По телу ответа их не отличить, ориентируйтесь на заголовок Idempotent-Replayed: его нет — ответ свежий.

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

Срок жизни ключа по умолчанию не применяется — поле 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 не показывает, успел ли выписаться ключ. Если ключ уже выписан, а карточку создать не удалось, место в квоте занято — найдите и отзовите лишний ключ. Если сам шаг выписки бросил ошибку, ключа, как правило, нет, но исход всё равно записан. В обоих случаях повтор с тем же ключом идемпотентности в течение 20 минут возвращает сохранённый отказ, а заголовок Idempotent-Replayed: true сам по себе не доказывает, что лишний ключ есть, — сверьтесь со списком ключей. Если не удалась сама вставка заявки на бронь, ни ключа, ни карточки нет — бронь не была занята, сохранённого исхода тоже нет, и повтор выполняется как новая попытка сразу.

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

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

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

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