## Block catalog

`GET /v1/block-repository`

Returns the Bitrix24 account's block catalog grouped by section — this is where you get the block code to add to a page. The catalog is shared across the whole Bitrix24 account and does not depend on a site or page.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `section` (query) | string | no | Catalog section code — a key of the `data` object in the response without the parameter, for example `text` or `cover`. With the parameter, `data` contains only this section |
| `scope` (query) | string | no | Site area: `KNOWLEDGE` — knowledge base, `GROUP` — workgroup pages, `MAINPAGE` — main pages. For other sites, omit the parameter |

**Pagination.** The method has no `limit` and `offset` parameters: the catalog or a section is returned in full in a single call.

## Examples

### curl — personal key

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

### curl — OAuth application

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

### JavaScript — personal key

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

const { data: section } = await res.json()
// The item key in items is the block code for POST /v1/pages/:pageId/blocks
for (const [code, block] of Object.entries(section.items)) {
  console.log(code, block.name)
}
```

### JavaScript — OAuth application

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

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

## Response fields

Without the `section` parameter, the `data` object is a dictionary of sections: the key is the section code, the value is the section object. With the `section` parameter, `data` holds the section object directly, and the paths below are read without the `<section>` segment.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Dictionary of catalog sections, or a single section with `section` |
| `data.<section>.name` | string | Section name in the Bitrix24 account language. Can be an empty string |
| `data.<section>.meta` | object \| array | Service data of the section: an object or, if there is no data, an empty array `[]`. Application sections do not have this field |
| `data.<section>.new` | boolean | New section flag |
| `data.<section>.type` | array \| null | Site types the section applies to, for example `["page", "store", "smn"]`, or `null`. Application sections do not have this field |
| `data.<section>.specialType` | string \| null | Service type of the section, `null` on the tested Bitrix24 account. Application sections do not have this field |
| `data.<section>.separator` | boolean | Service flag of the section, `false` on the tested Bitrix24 account |
| `data.<section>.app_code` | string \| boolean | Code of the application that added the section, or `false` for a built-in section |
| `data.<section>.items` | object \| array | Section blocks. The key is the block code, passed in the `code` field when [adding a block](/docs/entities/pages/blocks/create). An empty section has an empty array `[]` |
| `data.<section>.items.<code>.id` | null | Always `null`. A catalog block is identified by its key in `items`, not by this field |
| `data.<section>.items.<code>.name` | string | Block name in the Bitrix24 account language |
| `data.<section>.items.<code>.description` | string \| null | Block description. Can be an empty string. Application blocks return `null` |
| `data.<section>.items.<code>.namespace` | string | Block source: `bitrix` for built-in blocks, the application code for application blocks |
| `data.<section>.items.<code>.section` | array | Codes of all sections the block belongs to |
| `data.<section>.items.<code>.type` | array | Site types the block applies to, for example `["page", "store"]`. Can be an empty array |
| `data.<section>.items.<code>.preview` | string | Preview image URL. For built-in blocks the address has no scheme and starts with `//` |
| `data.<section>.items.<code>.new` | boolean | New block flag |
| `data.<section>.items.<code>.restricted` | boolean | Restricted block flag. On the tested Bitrix24 account, `true` for application blocks |
| `data.<section>.items.<code>.repo_id` | string \| boolean | Application block number as a string, `false` for built-in blocks. The key of such a block in `items` has the form `repo_<number>` |
| `data.<section>.items.<code>.app_code` | string \| boolean | Code of the application that added the block, or `false` |
| `data.<section>.items.<code>.requires_updates` | boolean | Service flag of the block, `false` on the tested Bitrix24 account |
| `data.<section>.items.<code>.version` | string \| null | Version number as a string, for example `18.5.0`, or `null`. Built-in blocks only |
| `data.<section>.items.<code>.system` | boolean | Service flag of the block. Built-in blocks only |
| `data.<section>.items.<code>.only_for_license` | string | License label as a string, can be empty. Built-in blocks only |

## Response example

Response to `GET /v1/block-repository?section=text`, showing one block from the section:

```json
{
  "success": true,
  "data": {
    "name": "Text",
    "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": "Full-width 3-column text on a colored background",
        "namespace": "bitrix",
        "new": false,
        "version": null,
        "type": [],
        "section": ["columns", "text"],
        "system": false,
        "description": "Three columns with titles and text",
        "preview": "//your-portal.bitrix24.com/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
      }
    }
  }
}
```

Response to `GET /v1/block-repository` without parameters, showing two catalog sections and one block. For the empty `favourite` section, the `items` field is returned as an array:

```json
{
  "success": true,
  "data": {
    "favourite": {
      "name": "",
      "meta": [],
      "new": false,
      "type": null,
      "specialType": null,
      "separator": false,
      "app_code": false,
      "items": []
    },
    "text": {
      "name": "Text",
      "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": "Full-width 3-column text on a colored background",
          "namespace": "bitrix",
          "new": false,
          "version": null,
          "type": [],
          "section": ["columns", "text"],
          "system": false,
          "description": "Three columns with titles and text",
          "preview": "//your-portal.bitrix24.com/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
        }
      }
    }
  }
}
```

## Error response example

404 — no section with this code:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 404 | `SECTION_NOT_FOUND` | The Bitrix24 account catalog has no section with the code from `section` |
| 400 | `INVALID_SCOPE` | `scope` is not one of `KNOWLEDGE`, `GROUP`, `MAINPAGE` |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the request: a required parameter is missing |
| 413 | `RESPONSE_TOO_LARGE` | The catalog is larger than 5 MB. Request one section at a time via `section` |
| 502 | `BLOCK_REPOSITORY_UNCONFIRMED` | Bitrix24 did not return the catalog. Retry the request |
| 403 | `BITRIX_ACCESS_DENIED` | The user the key was issued under has no site permissions in Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The error text is in `message` |
| 403 | `SCOPE_DENIED` | The API key does not have the `landing` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**One block in several sections.** A block is repeated in every section listed in its `section` field. When collecting a list of codes across the whole catalog, deduplicate by the block key.

**The full catalog is about a megabyte.** On the tested Bitrix24 account the catalog contains 33 sections and about 1500 blocks, and the response is about 950 KB. If you need one type of block, request the section via `section`.

**Catalog contents depend on the Bitrix24 account.** Installed applications add their own sections, and the code of such a section matches the application code, for example `krayt.monotovar`. Some sections have Cyrillic codes — pass the `section` value URL-encoded, for example via `encodeURIComponent`.

## See also

- [Add a block](/docs/entities/pages/blocks/create)
- [List page blocks](/docs/entities/pages/blocks/list)
- [Catalog sample](/docs/entities/pages/catalog-content)
- [Catalog manifest](/docs/entities/pages/catalog-manifest)
- [Pages](/docs/entities/pages)