Самоописание ключа

Необязательный объект data.deployment.standalone.reuseTarget содержит serverId существующего подходящего сервера, kind: "STANDALONE", action: "deploy" и createRequired: false. При его наличии checklist ведёт к тому же серверу вместо создания нового; это не разрешение перезаписать работающий код без проверки. Сигнал возможен и при capabilities.servers.create.available: false, поскольку новая VM не создаётся. GET ничего не восстанавливает: пустая личная привязка карточки заполняется только при create-reuse или уже авторизованном деплое на точный id. Состояние повторно проверяется на write-пути.

GET /v1/me

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

Форма ответа зависит от типа ключа. Как ключ передаётся в запросе — Передача ключа.

Создание приложения по инструкции

Если пользователь передал промпт создания, выполните шаги ниже до публикации приложения.

1. Прочитайте полный успешный ответ GET /v1/me с переданным ключом в заголовке X-Api-Key. Через MCP вызовите полный get_me({}) без sections. До выбора оформления и вопросов о месте использования или бренде примените data.uiDesign с policyVersion=2 (в MCP — поле uiDesign).
2. Для стандартного нового приложения без указанного места использования при context.status=portal_bound примените светлый дизайн Битрикс24 без вопроса о месте или бренде. Явное пожелание пользователя об оформлении имеет приоритет; для явно внешней страницы уточните бренд. При unresolved выберите аккаунт Битрикс24 и повторите запрос с его ключом приложения либо уточните назначение. Привязка ключа не доказывает встраивание и не даёт прав на создание, встраивание или публикацию: проверьте их отдельно. Существующий интерфейс сохраняет оформление; приложение без интерфейса не требует стилей. Для нового интерфейса следуйте uiDesign.instructions и uiDesign.css, закрепив указанную версию стилей.
3. Если запрос не удался, блок uiDesign отсутствует или версия политики не поддерживается, сообщите, что правило оформления не прочитано, и уточните оформление.
4. Если есть ссылка на ТЗ чертежа, прочитайте его с переданным ключом и кратко сверьте с пользователем требования по пунктам. Без ТЗ задайте не больше трёх коротких вопросов о том, что приложение должно делать и какие данные использовать. Учитывайте уже указанные требования и выбранное по правилу оформление, затем покажите короткий план.
5. Создайте приложение и разместите его на сервере по data.deployment и инструкции публикации. Если в промпте указан идентификатор сервера, используйте его. Для уже готового приложения выполняйте только публикацию, без повторного опроса и смены оформления.

Параметры

Примеры

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

curl https://vibecode.bitrix24.tech/v1/me \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl https://vibecode.bitrix24.tech/v1/me \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/me', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Тип ключа:', data.type, '· портал:', data.portal)

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/me', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Ответ описывает ключ, а не сущность портала. Верхнеуровневые блоки data.* — это карта возможностей: часть блоков общая для всех ключей, часть появляется только у ключа определённого типа. В колонке «Тип ключа» указано, для какого ключа блок присутствует.

Если вы знакомитесь с ключом впервые, достаточно четырёх блоков. type говорит, каким ключом вы работаете. scopes — к каким данным есть доступ. accessMode — разрешена ли запись. capabilities — какие операции доступны на этом портале и по какой причине отказано в остальных. Остальные блоки нужны под конкретную задачу: deployment и infra — при работе с серверами, ai и webSearch — при вызовах моделей, storage — при загрузке файлов.

Для облачного RU-портала bindPrerequisite.errorCodes дополнительно включает B24_EMBEDDING_INSTALL_DENIED. Этот отказ означает, что при действующей подписке Маркетплейса остаётся ограничение на установку приложения; на коробке и в остальных регионах этот код в набор не входит.

Менеджмент-ключ (vibe_live_) возвращает другой набор блоков — portals, totalAppKeys, урезанный capabilities — и не несёт данных портала. Описание — Менеджмент-ключи.

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

Личный ключ (vibe_api_) — показаны основные поля:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "portalId": "8c3d1e04-…",
    "tariff": {
      "code": "ru_basic",
      "name": "Базовый",
      "isCommercial": true,
      "wasEverCommercial": true,
      "checkedAt": "2026-07-08T08:57:58.270Z",
      "kind": "CLOUD"
    },
    "scopes": ["crm", "task", "tasks", "im", "imbot", "disk", "user"],
    "accessMode": "READWRITE",
    "capabilities": {
      "apps": {
        "create": { "available": true },
        "publish": { "available": true },
        "bindPlacements": { "available": true }
      },
      "servers": {
        "create": { "available": true, "reason": "COMMERCIAL" },
        "deploy": { "available": true, "reason": "COMMERCIAL" },
        "preview": { "available": true },
        "wake": { "available": true }
      },
      "agents": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Agent servers count toward the portal's infrastructure limit (currently 2/10)."
        }
      },
      "managedBots": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Managed bot servers count toward the portal infrastructure limit."
        }
      },
      "aiRouter": {
        "chatCompletions": { "available": true },
        "byok": { "available": true }
      },
      "appUserSignIn": {
        "setup": { "available": false, "reason": "FEATURE_DISABLED" }
      }
    },
    "owner": { "name": "Иван Петров", "userId": "1" },
    "expiresAt": null
  }
}

У слотов apps.publish и apps.bindPlacements поле note приходит всегда — в примере выше оно опущено, полный текст возвращает сам эндпоинт.

Ключ авторизации (vibe_app_) без токена сессии — показаны блоки, которых нет у личного ключа:

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.ru",
    "portalId": "8c3d1e04-…",
    "accessMode": "READWRITE",
    "app": { "title": "CRM Dashboard", "id": "f2342f7a-…" },
    "currentUser": null,
    "placements": {
      "available": true,
      "registered": ["LEFT_MENU"],
      "endpoints": [
        "POST https://vibecode.bitrix24.tech/v1/placements/bind",
        "POST https://vibecode.bitrix24.tech/v1/placements/unbind",
        "GET https://vibecode.bitrix24.tech/v1/placements",
        "GET https://vibecode.bitrix24.tech/v1/placements/available"
      ],
      "bindPrerequisite": {
        "subscriptionRequired": true,
        "note": "Binding a placement requires a Bitrix24-side prerequisite that depends on the dispatch path…",
        "errorCodes": [
          "B24_MARKET_SUBSCRIPTION_REQUIRED",
          "B24_MARKET_TRIAL_USED",
          "BITRIX_UNAVAILABLE",
          "BOX_WEBHOOK_NOT_DEVELOPER_KEY",
          "PLACEMENT_APP_GRANT_MISSING",
          "PLACEMENT_OPTIONS_REQUIRED",
          "PLACEMENT_NOT_REST_BINDABLE",
          "B24_EMBEDDING_APP_NOT_FOUND",
          "B24_EMBEDDING_INSTALL_DENIED"
        ]
      }
    }
  }
}

oauth.authorizeUrl — это шаблон, а не готовая ссылка. Эндпоинт /v1/oauth/authorize требует обязательный параметр state (16–512 символов) — это CSRF-токен по RFC 6749 §10.12, который генерирует клиент: создайте криптослучайную строку, добавьте её в URL и сверьте значение, вернувшееся в callback. Сервер не может сгенерировать state за вас — иначе защита от CSRF не работает. Запрос по authorizeUrl как есть вернёт 400 INVALID_REQUEST "state: Required". Опционально добавьте redirect_uri — ваш адрес возврата, без него используется встроенная страница /oauth/complete, — и scope. Пример полной ссылки:

Скопировать

https://vibecode.bitrix24.tech/v1/oauth/authorize?app_key=vibe_app_…&state=aAbBcCdDeEfFgGhH&redirect_uri=https://myapp.com/callback

Запрос по этой ссылке делает сервер приложения: в ней app_key, поэтому браузеру её не передавайте. Браузер пользователя перенаправьте на адрес из заголовка Location в ответе — шаг 1 авторизации.

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

401 — неверный ключ:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Ошибки

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

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

?refresh=tariff проверяет тариф не чаще одного раза в минуту. Параметр форсирует живую проверку тарифа портала в Битрикс24 и сбрасывает кэш ответа. Если предыдущая проверка была меньше минуты назад, запрос возвращает уже известное значение без новой проверки. Для менеджмент-ключа параметр не делает ничего — такой ключ не привязан к порталу.

Ответ кэшируется на стороне сервера около 30 секунд. Смена скоупов или режима доступа отражается в ответе сразу. Тариф, баланс и состояние инфраструктуры обновляются при первом чтении после истечения кэша. Запрос с ?refresh=tariff сбрасывает кэш, и следующее чтение без этого параметра отдаёт свежий тариф.

У ключа в режиме «только чтение» часть слотов capabilities приходит закрытыми. Это apps.publish, apps.bindPlacements, servers.create, servers.wake, agents.create, managedBots.create и обе операции aiRouter — все они отдают available: false и reason: "WRITE_BLOCKED_READONLY_KEY". Слот servers.deploy в этот список не входит: доставка на уже свой сервер такому ключу разрешена. У ключа «только чтение» в корне ответа приходит и поле writeRestriction — код WRITE_BLOCKED_READONLY_KEY, область действия и ссылка на страницу про режимы. Поле появляется только пока запрет включён: платформенный админ вправе его снять, и тогда поле из ответа исчезает вместе с самим запретом. Внутри поля есть список exceptions — маршруты, которые центральный запрет не трогает. Читайте состав из ответа, а не из прозы этой страницы; напечатанный состав с разбором по группам — на странице Режим доступа, раздел «Исключения из запрета записи». У управляющего ключа поле тоже приходит, но снять его нельзя ничем: запрет записи для таких ключей безусловен. Оно нужно потому, что тело ответа называет пишущие ручки в трёх десятках мест (подсказки хранилища, обращений, автосохранения исходников, коворка): это адреса, а не разрешения. Доступность конкретной операции — в capabilities.

Заявлений о запрете два, и они про разное. Рядом с writeRestriction у того же ключа приходит portalWriteRestriction — про изменение данных Битрикс24: код, область, список маршрутов, у каждой записи которого своё условие отказа, и ссылка на страницу режима. writeRestriction описывает платформенные записи и исчезает, если платформенный админ снимает этот запрет аварийным рычагом. portalWriteRestriction описывает данные Битрикс24 и от этого рычага не зависит: делегированные записи в Битрикс24 отказывают и при снятом платформенном запрете. Состав маршрутов читайте из ответа — раздел «Поле portalWriteRestriction» на странице режима объясняет группы.

Слот apps.create закрытым НЕ приходит: приложение в режиме READONLY таким ключом создаётся, а запрет на режим READWRITE описан в поле note этого слота. Чтения режим не затрагивает — например, servers.preview. Подробнее — Режим доступа.

Название тарифа предназначено для показа, а не для сравнения. Поле data.tariff.name собирается при чтении и может меняться, не меняя самого тарифа. Платформа берёт его по такому порядку. Если код тарифа известен справочнику редакций — оттуда, на русском языке. Иначе — название лицензии, как его сообщил Битрикс24, на языке портала. Иначе — сохранённое ранее название. Иначе — null. Из этого следуют три вещи. Первая: null — штатное значение, а не ошибка. Вторая: название не зависит от того, кто спрашивает, — его не меняют ни Accept-Language, ни язык интерфейса владельца ключа. Третья: код тарифа вместо названия не подставляется никогда — если названия нет, приходит null, а не pro100. Ветвить логику нужно по data.tariff.code, isCommercial и kind. Подписи известных редакций при этом уточнены — три из них: «Демо» стало «Демо-период», «Проект» — «Проект — архивный бесплатный», «NFR» — «NFR — партнёрская лицензия».

Признак wasEverCommercial — история, а не доступ. Значение true означает лишь, что портал когда-либо наблюдался на коммерческом тарифе. Доступа к инфраструктуре и режиму OPEN признак не даёт и отказов в этом доступе не снимает: доступ считается только по текущему состоянию портала — тарифу, подписке и демо. Решение принимайте по capabilities в этом же ответе, а не по признаку.

Признак wasEverCommercial не односторонний. Понижение тарифа значение не сбрасывает, но платформа может сменить его с true на false, если оснований под признаком не нашлось. Логику, которая считает переход возможным только в одну сторону, на этом поле строить нельзя.

Модель размещения определяйте по блоку deployment, а не по тарифу портала. На бесплатном тарифе Битрикс24 новая галактика не создаётся. Если режим галактик включён, но хоста нет, deployment.galaxyApp отсутствует, deployment.primary равен standalone, а deployment.placementNote описывает двухшаговый путь. Он доступен, только когда capabilities.servers.create.available в том же ответе равен true. Допустимый идентификатор тарифа выберите из capabilities.servers.create.limits.allowedPlans. При выключенном режиме галактик placementNote отсутствует, одношаговый запрос с source возвращает 400 SOURCE_AT_CREATE_GALAXY_ONLY, а возможность двухшагового пути определяется тем же слотом capabilities. Если существующий хост проходит предварительную проверку сохранённого состояния, блок galaxyApp присутствует и одношаговое создание с source стоит попробовать. Это не гарантия: текущую вместимость проверяет только POST /v1/infra/servers.

Если существующий хост не проходит предварительную проверку, блок galaxyApp отсутствует. Пока capabilities.servers.create.available равен false, placementNote запрещает двухшаговое создание отдельной машины: при включённом контроле trial-ограничений занятый слот даёт 402 TRIAL_PORTAL_LIMIT. Для нового одношагового запроса дождитесь восстановления хоста, попросите администратора починить его либо повысьте тариф. После удаления хоста заново прочитайте GET /v1/me и используйте объявленный там двухшаговый путь. Следуйте подсказке фактического ответа POST. Порядок вызовов — Создать сервер и Публикация.

Без ключа в браузере эндпоинт отдаёт HTML. Запрос GET /v1/me без заголовка X-Api-Key и с заголовком Accept: text/html возвращает страницу-заглушку со статусом 200, а не JSON. Запрос с ключом или без text/html в заголовке Accept всегда получает JSON-самоописание.

Карта требуемых прав

Раньше границу ключа можно было узнать только вызовом: запрос уходил и возвращался отказом 403 SCOPE_DENIED, называющим недостающее право. Список доступных сущностей показывал только открытое, а закрытое просто отсутствовало — и по отсутствию нельзя было отличить «такой сущности нет в продукте» от «она есть, но вашему ключу закрыта».

Блок data.api.scopeRequirements отвечает на этот вопрос до вызова:

{
  "granted": { "bitrix24": ["imbot"], "platform": ["vibe:ai", "vibe:search"] },
  "missing": {
    "bitrix24": {
      "crm": {
        "entities": ["deals", "contacts", "companies", "leads"],
        "unlocks": ["/v1/duplicates/find", "/v1/addresses"],
        "unlocksRemaining": 41,
        "truncated": true,
        "howToObtain": "reissue-key"
      }
    },
    "platform": {}
  }
}

Права Битрикс24 закрепляются за ключом в момент выпуска, поэтому howToObtain у них — reissue-key: добавить право в настройках уже выпущенного ключа недостаточно, нужен перевыпуск. Права Вайбкод правятся в кабинете.

Карта описывает только проверку прав на стороне платформы. Она не обещает, что вызов пройдёт. Право, выданное в кабинете уже после выпуска ключа, попадёт в карту, но Битрикс24 его не признает и ответит BITRIX_ACCESS_DENIED. Отказы по виду ключа, владению, режиму только для чтения, заморозке и тарифу — отдельные оси, и в карте они не описаны. Об этом же предупреждает поле _note внутри блока.

Перечень путей пока неполон, и карта говорит об этом сама. Поле coverage.paths со значением partial означает, что часть кастомных роутов ещё не имеет машинного вердикта, поэтому unlocks и unlocksRemaining занижают. Отсутствие пути в списке НЕ доказывает, что путь не гейтится: если вызов всё-таки отвечает отказом по правам, верьте отказу, а не карте. Список сущностей при этом полон всегда.

Отбивка не изменилась: вызов без нужного права по-прежнему возвращает 403 SCOPE_DENIED с именем этого права. Карта добавлена как предварительная проверка, а не как замена отбивки.

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

• Ключи и авторизация
• Справочник API для модели
• Режим доступа
• Скоупы
• Менеджмент-ключи
• Ошибки