Для AI-агентов: markdown этой страницы — /docs-content/keys-auth/guide.md индекс документации — /llms.txt
Справочник API для модели
GET /v1/guide
Возвращает контракт полей всех сущностей портала и правила работы с API одним ответом. Модель обращается к нему за статической схемой полей до появления токена сессии — например, когда приложению нужно узнать типы и ограничения полей ещё до авторизации пользователя.
Примеры
curl — личный ключ
curl -H "X-Api-Key: YOUR_API_KEY" \
https://vibecode.bitrix24.tech/v1/guide
curl — OAuth-приложение
curl \
-H "X-Api-Key: YOUR_APP_KEY" \
https://vibecode.bitrix24.tech/v1/guide
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-приложение
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 и часть несущих блоков. Полный ответ содержит контракты всех сущностей, доступных ключу.
{
"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 — не передан ключ:
{
"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 с пользовательским контекстом.