Для 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.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[].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>.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.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 string Указатели на разделы документации — URL и краткое описание раздела
data.workflows, data.notifications, data.calls, data.keysAuth и другие разделы object Разделы за пределами entity-API. Каждый содержит description, массив endpoints с методами и путями и docs со ссылками на документацию

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

Показаны один элемент 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: new features (NEW), fixes (FIX), breaking changes (BC), newest first."
  }
}

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

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

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

Ошибки

HTTP Код Описание
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key
401 INVALID_API_KEY Ключ не найден
401 KEY_INACTIVE Ключ отозван
401 KEY_EXPIRED Срок действия ключа прошёл
403 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 с пользовательским контекстом.

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