Для AI-агентов: markdown этой страницы — /docs-content/keys-auth/guide.md индекс документации — /llms.txt

Справочник API для модели

GET /v1/guide

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

Примеры

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

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

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

Terminal
curl \
  -H "X-Api-Key: YOUR_APP_KEY" \
  https://vibecode.bitrix24.tech/v1/guide

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/guide', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.entities.forEach((e) => {
  console.log(`${e.name} (${e.scope}) — ${Object.keys(e.operations).join(', ')}`)
})

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/guide', {
  headers: { 'X-Api-Key': 'YOUR_APP_KEY' },
})

const { data } = await res.json()

Поля ответа

Ответ разбит на несущие блоки: data.overview — обзор, data.entities — контракты сущностей, data.paginationCanon — общие для всех сущностей правила листания и подсчёта, data.importantNotes и data.knownIssues — тонкости и ограничения, плюс указатели на разделы документации. Ниже — конверт ответа, структура элемента data.entities[] и вложенный контракт поля fieldsDetailed.

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеСправочник: обзор, контракты сущностей, правила работы с API
Полеdata.overview Типstring ОписаниеОбзорное описание доступной поверхности API
Полеdata.entities Типarray ОписаниеКонтракты сущностей, доступных ключу
Полеdata.entities[].name Типstring ОписаниеИдентификатор сущности для путей /v1/<name>
Полеdata.entities[].basePath Типstring ОписаниеБазовый путь сущности. Для динамических сущностей содержит сегмент параметра, например /v1/items/:entityTypeId
Полеdata.entities[].scope Типstring ОписаниеСкоуп, необходимый для доступа к сущности
Полеdata.entities[].bitrixEntity Типstring ОписаниеИмя сущности на стороне Битрикс24
Полеdata.entities[].operations Типobject ОписаниеДоступные операции. Ключи — list, getById, create, update, delete, search, aggregate, batch. Присутствуют только поддерживаемые операции
Полеdata.entities[].operations.<op>.method Типstring ОписаниеHTTP-метод операции
Полеdata.entities[].operations.<op>.path Типstring ОписаниеПуть операции. У части операций рядом приходят params, example, note, requiredParams
Полеdata.entities[].operations.search.paginationStability.counting Типstring ОписаниеКак узнать точное количество записей этой сущности. Приходит со своим текстом у каждой сущности, потому что зависит от того, доступна ли ей операция агрегации
Полеdata.entities[].fields Типobject ОписаниеКомпактная карта полей: имя поля соответствует строке тип или тип, readonly
Полеdata.entities[].fieldsDetailed Типobject ОписаниеПодробный контракт полей: имя поля соответствует объекту с типом и ограничениями
Полеdata.entities[].fieldsDetailed.<field>.type Типstring ОписаниеТип поля
Полеdata.entities[].fieldsDetailed.<field>.readonly Типboolean ОписаниеПоле только для чтения. Приходит, когда true
Полеdata.entities[].fieldsDetailed.<field>.required Типboolean ОписаниеПоле обязательно при создании. Приходит, когда true
Полеdata.entities[].fieldsDetailed.<field>.createOnly Типboolean ОписаниеПоле задаётся только при создании и не принимается при обновлении. Приходит, когда true
Полеdata.entities[].fieldsDetailed.<field>.nullable Типboolean ОписаниеПоле может прийти со значением null. Приходит, когда true
Полеdata.entities[].fieldsDetailed.<field>.importable Типboolean ОписаниеПоле можно задать только при импорте. Приходит, когда true
Полеdata.entities[].fieldsDetailed.<field>.properties Типobject ОписаниеКарта вложенных полей объекта. Рекурсивно использует type, readonly, nullable, properties, itemSchema
Полеdata.entities[].fieldsDetailed.<field>.itemSchema Типobject ОписаниеСхема одного элемента массива. Приходит для поля типа array с объявленной формой элемента и рекурсивно использует type, readonly, nullable, properties, itemSchema
Полеdata.entities[].fieldsDetailed.<field>.enum Типarray ОписаниеДопустимые значения поля-перечисления
Полеdata.entities[].fieldsDetailed.<field>.enum[].value Типnumber или string ОписаниеЗначение, которое принимает поле
Полеdata.entities[].fieldsDetailed.<field>.enum[].label Типstring ОписаниеАнглийское название значения
Полеdata.entities[].fieldsDetailed.<field>.enum[].labelRu Типstring ОписаниеРусское название значения
Полеdata.entities[].fieldsDetailed.<field>.enum[].description Типstring ОписаниеПояснение значения. Приходит не для всех значений
Полеdata.entities[].responseFormats Типobject ОписаниеПримеры формы ответа для операций list, get, create
Полеdata.entities[].docs Типstring ОписаниеСсылка на страницу документации сущности. Приходит, если страница существует
Полеdata.entities[].requiredListParams Типarray ОписаниеОбязательные query-параметры операции list. Приходит для сущностей, которые их требуют
Полеdata.entities[].requiredFilterFields Типarray ОписаниеОбязательные поля фильтра. Приходит для сущностей, которые их требуют
Полеdata.paginationCanon Типobject ОписаниеПравила листания и подсчёта записей, общие для всех сущностей: withTotal, windowing, defaultOrder, preferredPattern, unstableOffsetError, workaround, cursor, loopBound. Одноимённые поля внутри data.entities[].operations.search содержат указатель сюда и текста не повторяют
Полеdata.paginationCanon.appliesTo Типstring ОписаниеК каким сущностям относится блок и что из правил приходит не здесь, а рядом с сущностью
Полеdata.importantNotes Типobject ОписаниеТонкости работы с полями, общие для нескольких сущностей — формат stageId, денежные поля сделки и другие
Полеdata.knownIssues Типarray ОписаниеИзвестные ограничения методов, отфильтрованные по скоупам ключа
Полеdata.knownIssues[].method Типstring ОписаниеМетод Битрикс24, к которому относится ограничение
Полеdata.knownIssues[].scope Типstring ОписаниеСкоуп метода
Полеdata.knownIssues[].issue Типstring ОписаниеОписание ограничения
Полеdata.knownIssues[].workaround Типstring ОписаниеОбходной путь
Полеdata.accessModeNote Типstring ОписаниеНапоминание о режиме «только чтение» и коде WRITE_BLOCKED_READONLY_KEY
Полеdata.changelog, data.errors, data.feedback, data.entityApi, data.entitiesIndex, data.optimization, data.filtering, data.batch и другие строковые указатели Типstring ОписаниеУказатели на разделы документации — URL и краткое описание раздела
Полеdata.appBlueprints Типstring ОписаниеУказатель на документацию готовых технических заданий приложений. Приходит любому ключу. Описание называет и условие отказа: при выключенном для аккаунта разделе GET /v1/app/blueprints/:slug отвечает 403 BLUEPRINTS_DISABLED
Полеdata.workflows, data.notifications, data.calls, data.keysAuth и другие разделы Типobject ОписаниеРазделы за пределами entity-API. Каждый содержит description, docs со ссылками на документацию и — у большинства разделов — массив endpoints с методами и путями. Часть разделов вместо endpoints несёт массив important с ограничениями раздела
Полеdata.openLines Типobject ОписаниеРаздел открытых линий. Приходит ключу со скоупом imopenlines. Содержит description, scope, массив important и docs со ссылками на восемь страниц раздела. Массива endpoints в этом блоке нет
Полеdata.openLines.important Типarray ОписаниеДва ограничения раздела: методы статистики дашборда могут ответить 422 METHOD_NOT_YET_AVAILABLE, если обновление Битрикс24 ещё не пришло на портал, а без права на просмотр статистики — 403 B24_TARIFF_RESTRICTION. GET /v1/guide портал не опрашивает: это общее уведомление, а не статус вашего портала — вызовите метод, ответ 200 значит, что он здесь работает. Настройка линий и действия оператора работают на любом портале

itemSchema имеет одинаковую форму в fieldsDetailed и в ответах GET /v1/<entity>/fields. Отдельный ключ items в ответе /fields по-прежнему содержит сырой справочник значений Битрикс24 у полей-перечислений и никогда не содержит схему элемента массива.

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

Показаны один элемент data.entities и часть несущих блоков. Полный ответ содержит контракты всех сущностей, доступных ключу.

JSON
{
  "success": true,
  "data": {
    "overview": "VibeCode API proxies Bitrix24 REST API. 48 entities across CRM, tasks, users, calendar, disk, chat, and more.",
    "entities": [
      {
        "name": "deals",
        "basePath": "/v1/deals",
        "scope": "crm",
        "bitrixEntity": "deal",
        "operations": {
          "list": { "method": "GET", "path": "/v1/deals", "params": ["limit", "offset"] },
          "getById": { "method": "GET", "path": "/v1/deals/:id" },
          "create": { "method": "POST", "path": "/v1/deals" }
        },
        "fields": {
          "id": "number, readonly",
          "title": "string",
          "amount": "number",
          "currency": "string"
        },
        "fieldsDetailed": {
          "id": { "type": "number", "readonly": true },
          "title": { "type": "string" },
          "amount": { "type": "number" },
          "currency": { "type": "string" }
        },
        "responseFormats": {
          "list": "GET /v1/deals → { success: true, data: [{ id, xmlId, lastActivityTime, title, ... }], meta: { total, hasMore } }"
        },
        "docs": "https://vibecode.bitrix24.tech/docs-content/entities/deals.md"
      }
    ],
    "importantNotes": {
      "stageIdFormat": {
        "description": "Deal stageId values use Bitrix24 category prefix format: C{categoryId}:{STAGE_CODE}."
      }
    },
    "knownIssues": [
      {
        "method": "crm.timeline.comment.list",
        "scope": "crm",
        "issue": "Ignores >=CREATED filter (date filtering does not work)",
        "workaround": "Fetch all comments and filter by date on client side"
      }
    ],
    "accessModeNote": "See /v1/me for current accessMode. Write methods return 403 WRITE_BLOCKED_READONLY_KEY when key is READONLY.",
    "changelog": "https://vibecode.bitrix24.tech/docs-content/changelog.md — API changelog index: scheduled removals of old formats, a monthly archive and per-section history. Full entries (NEW / FIX / BC) are on per-day pages."
  }
}

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

401 — не передан ключ:

JSON
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Ошибки

HTTP Код Описание
HTTP401 КодMISSING_API_KEY ОписаниеОтсутствует заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан: такой строки на платформе нет
HTTP401 КодKEY_INACTIVE ОписаниеКлюч отозван
HTTP401 КодKEY_EXPIRED ОписаниеСрок действия ключа прошёл
HTTP403 КодIP_NOT_ALLOWED ОписаниеЗапрос с адреса вне списка разрешённых IP

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

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

Токен сессии не нужен. Ключ авторизации vibe_app_ читает контракт data.entities[].fieldsDetailed по одному заголовку X-Api-Key, без Authorization: Bearer. Это отличает эндпоинт от GET /v1/<entity>/fields, которому нужен пользовательский контекст. См. Передача ключа.

Состав data.entities зависит от ключа. Ключ видит только сущности своих скоупов. Ключ авторизации дополнительно получает сущности бизнес-процессов, доступные приложению. Менеджмент-ключ получает справочник по всем скоупам и дополнительный блок data.managementKeyNote.

Ответ отдаётся целиком. Эндпоинт не принимает параметров запроса: получить одну сущность или один раздел справочника нельзя, неизвестный параметр запроса игнорируется и ответ не меняется. Чтобы не читать ответ целиком при каждом запуске, опирайтесь на ETag и условные запросы.

Условные запросы и кэш. Ответ несёт заголовок ETag. Повторный запрос с If-None-Match и тем же значением возвращает 304 Not Modified без тела. Ответ кэшируется на стороне сервера около 5 минут, заголовок ответа — Cache-Control: private, max-age=300.

fieldsDetailed — статический контракт. Он не содержит отображаемых названий полей и пользовательских полей портала UF_CRM_*. За отображаемыми названиями и пользовательскими полями обращайтесь к GET /v1/<entity>/fields с пользовательским контекстом.

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