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

`GET /v1/block-repository`

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

## Параметры

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

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

## Примеры

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

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

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

```bash
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` при [добавлении блока](/docs/entities/pages/blocks/create). У пустого раздела — пустой массив `[]` |
| `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 — [Ошибки](/docs/errors).

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

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

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

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

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

- [Добавить блок](/docs/entities/pages/blocks/create)
- [Список блоков страницы](/docs/entities/pages/blocks/list)
- [Образец каталога](/docs/entities/pages/catalog-content)
- [Манифест каталога](/docs/entities/pages/catalog-manifest)
- [Страницы](/docs/entities/pages)