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

Каталог блоков

GET /v1/block-repository

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

Параметры

Параметр Тип Обяз. Описание
section (query) string нет Код раздела каталога — ключ объекта data в ответе без параметра, например text или cover. С параметром в data приходит только этот раздел
scope (query) string нет Область сайта: KNOWLEDGE — база знаний, GROUP — страницы рабочих групп, MAINPAGE — главные страницы. Для остальных сайтов параметр не передаётся

Пагинация. Параметров limit и offset у метода нет: каталог или раздел приходит целиком за один вызов.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/block-repository?section=text" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/block-repository?section=text" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

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

const { data: section } = await res.json()
// Ключ элемента в items — код блока для POST /v1/pages/:pageId/blocks
for (const [code, block] of Object.entries(section.items)) {
  console.log(code, block.name)
}

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/block-repository?section=text', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data: section } = await res.json()

Поля ответа

Без параметра section объект data — словарь разделов: ключ — код раздела, значение — объект раздела. С параметром section в data сразу объект раздела, и пути ниже читаются без сегмента <раздел>.

Поле Тип Описание
success boolean Всегда true при успехе
data object Словарь разделов каталога или один раздел при section
data.<раздел>.name string Название раздела на языке портала. Может быть пустой строкой
data.<раздел>.meta object | array Служебные данные раздела: объект или, если данных нет, пустой массив []. У разделов приложений поля нет
data.<раздел>.new boolean Флаг нового раздела
data.<раздел>.type array | null Типы сайтов, к которым относится раздел, например ["page", "store", "smn"], либо null. У разделов приложений поля нет
data.<раздел>.specialType string | null Служебный тип раздела, на проверенном портале null. У разделов приложений поля нет
data.<раздел>.separator boolean Служебный флаг раздела, на проверенном портале false
data.<раздел>.app_code string | boolean Код приложения, которое добавило раздел, или false для встроенного раздела
data.<раздел>.items object | array Блоки раздела. Ключ — код блока, его передают в поле code при добавлении блока. У пустого раздела — пустой массив []
data.<раздел>.items.<код>.id null Приходит null. Блок в каталоге идентифицируется ключом в items, а не этим полем
data.<раздел>.items.<код>.name string Название блока на языке портала
data.<раздел>.items.<код>.description string | null Описание блока. Бывает пустой строкой, у блоков приложений — null
data.<раздел>.items.<код>.namespace string Источник блока: bitrix для встроенных блоков, код приложения для блоков приложений
data.<раздел>.items.<код>.section array Коды всех разделов, в которые входит блок
data.<раздел>.items.<код>.type array Типы сайтов, к которым относится блок, например ["page", "store"]. Бывает пустым массивом
data.<раздел>.items.<код>.preview string URL картинки предпросмотра. У встроенных блоков адрес без схемы, начинается с //
data.<раздел>.items.<код>.new boolean Флаг нового блока
data.<раздел>.items.<код>.restricted boolean Флаг ограниченного блока. На проверенном портале true у блоков приложений
data.<раздел>.items.<код>.repo_id string | boolean Номер блока приложения строкой, у встроенных блоков — false. Ключ такого блока в items имеет вид repo_<номер>
data.<раздел>.items.<код>.app_code string | boolean Код приложения, которое добавило блок, или false
data.<раздел>.items.<код>.requires_updates boolean Служебный флаг блока, на проверенном портале false
data.<раздел>.items.<код>.version string | null Номер версии строкой, например 18.5.0, или null. Только у встроенных блоков
data.<раздел>.items.<код>.system boolean Служебный флаг блока. Только у встроенных блоков
data.<раздел>.items.<код>.only_for_license string Метка лицензии строкой, бывает пустой. Только у встроенных блоков

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

Запрос GET /v1/block-repository?section=text, показан один блок из раздела:

JSON 
{
  "success": true,
  "data": {
    "name": "Текст",
    "meta": {
      "ai_text_placeholder": "text for website, family business, sale of flowers",
      "ai_text_max_tokens": 150
    },
    "new": false,
    "type": null,
    "specialType": null,
    "separator": false,
    "app_code": false,
    "items": {
      "03.1.three_cols_big_with_text_and_titles": {
        "id": null,
        "name": "Текст в 3 колонки на всю ширину страницы на цветном фоне",
        "namespace": "bitrix",
        "new": false,
        "version": null,
        "type": [],
        "section": ["columns", "text"],
        "system": false,
        "description": "Три колонки с заголовками и текстом",
        "preview": "//your-portal.bitrix24.ru/bitrix/blocks/bitrix/03.1.three_cols_big_with_text_and_titles/preview.jpg",
        "restricted": false,
        "repo_id": false,
        "app_code": false,
        "only_for_license": "",
        "requires_updates": false
      }
    }
  }
}

Запрос GET /v1/block-repository без параметров — показаны два раздела из каталога и один блок, у пустого раздела favourite поле items приходит массивом:

JSON 
{
  "success": true,
  "data": {
    "favourite": {
      "name": "",
      "meta": [],
      "new": false,
      "type": null,
      "specialType": null,
      "separator": false,
      "app_code": false,
      "items": []
    },
    "text": {
      "name": "Текст",
      "meta": {
        "ai_text_placeholder": "text for website, family business, sale of flowers",
        "ai_text_max_tokens": 150
      },
      "new": false,
      "type": null,
      "specialType": null,
      "separator": false,
      "app_code": false,
      "items": {
        "03.1.three_cols_big_with_text_and_titles": {
          "id": null,
          "name": "Текст в 3 колонки на всю ширину страницы на цветном фоне",
          "namespace": "bitrix",
          "new": false,
          "version": null,
          "type": [],
          "section": ["columns", "text"],
          "system": false,
          "description": "Три колонки с заголовками и текстом",
          "preview": "//your-portal.bitrix24.ru/bitrix/blocks/bitrix/03.1.three_cols_big_with_text_and_titles/preview.jpg",
          "restricted": false,
          "repo_id": false,
          "app_code": false,
          "only_for_license": "",
          "requires_updates": false
        }
      }
    }
  }
}

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

404 — раздела с таким кодом нет:

JSON 
{
  "success": false,
  "error": {
    "code": "SECTION_NOT_FOUND",
    "message": "No such repository section. Omit `section` to read the whole catalog."
  }
}

Ошибки

HTTP Код Описание
404 SECTION_NOT_FOUND Раздела с кодом из section нет в каталоге портала
400 INVALID_SCOPE scope не входит в KNOWLEDGE, GROUP, MAINPAGE
400 INVALID_PARAMS Битрикс24 отклонил запрос: не хватает обязательного параметра
413 RESPONSE_TOO_LARGE Каталог больше 5 МБ. Запрашивайте по одному разделу через section
502 BLOCK_REPOSITORY_UNCONFIRMED Битрикс24 не вернул каталог. Повторите запрос
403 BITRIX_ACCESS_DENIED У сотрудника, под которым выпущен ключ, нет прав на сайты в Битрикс24
422 BITRIX_ERROR Битрикс24 отклонил запрос, текст ошибки — в message
403 SCOPE_DENIED API-ключ не имеет скоупа landing
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Один блок — в нескольких разделах. Блок повторяется в каждом разделе, перечисленном в его поле section. Собирая список кодов по всему каталогу, убирайте повторы по ключу блока.

Каталог целиком — около мегабайта. На проверенном портале каталог содержит 33 раздела и около 1500 блоков, ответ занимает около 950 КБ. Если нужен один тип блоков, запрашивайте раздел через section.

Состав каталога зависит от портала. Установленные приложения добавляют свои разделы, код такого раздела совпадает с кодом приложения, например krayt.monotovar. Встречаются разделы с кодом на кириллице — значение section передавайте в URL-кодировке, например через encodeURIComponent.

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