## List page blocks `GET /v1/pages/:pageId/blocks` Returns the blocks of one site page in the order they appear on the page. ## Parameters | Parameter | Type | Required | Default | Description | |----------|-----|:-----:|-----------|---------| | `pageId` (path) | number | yes | — | Page ID. List: [`GET /v1/pages`](/docs/entities/pages/list) | | `version` (query) | string | no | `draft` | Page version: `draft` is the draft, `published` is what a site visitor sees | | `deleted` (query) | boolean | no | `false` | `true` returns the blocks in the page's trash instead of the blocks on the page | | `content` (query) | boolean | no | `false` | `true` adds each block's `content` markup and its `css` and `js` includes. The response grows by the HTML of all blocks on the page | | `scope` (query) | string | no | — | Site area: `KNOWLEDGE` for the knowledge base, `GROUP` for workgroup pages, `MAINPAGE` for main pages. Omit it for pages of all other sites | **Pagination.** The method has no `limit` or `offset` parameters: the response contains all blocks of the page in one call. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/pages/20/blocks" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/pages/20/blocks" \ -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/pages/20/blocks', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data, meta } = await res.json() console.log(`Version ${meta.version}, blocks: ${meta.count}`) for (const block of data) { console.log(block.id, block.code, block.active ? 'visible' : 'hidden') } ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data, meta } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | array | Page blocks in the order they appear on the page. An empty array if the page has no blocks | | `data[].id` | number | Block ID in the page version that was read | | `data[].pageId` | number | Page ID | | `data[].code` | string | Block code from the catalog. Catalog: [`GET /v1/block-repository`](/docs/entities/pages/catalog) | | `data[].name` | string | Block name in the Bitrix24 account language | | `data[].active` | boolean | `false` means the block is hidden on the page | | `data[].meta` | object | Service information about the block. Keys are upper case, all values are strings: `CREATED_BY_ID` and `MODIFIED_BY_ID` are employee IDs, `DATE_CREATE` and `DATE_MODIFY` are dates in the Bitrix24 account locale format, plus `DESIGNER_MODE`, `XML_ID` and others. `FAVORITE_META` arrives as the string `"Array"` and carries no data | | `data[].content` | string \| null | Only with `content=true`. Block HTML including the outer wrapper `
`. `null` for a hidden block | | `data[].css` | array | Only with `content=true`. Stylesheets the block includes | | `data[].js` | array | Only with `content=true`. Scripts the block includes | | `data[].version` | string | Version the block was read from: `draft` or `published` | | `meta.version` | string | Page version the request read: `draft` or `published` | | `meta.count` | number | Number of blocks in `data` | ## Response example A page draft with three blocks, the first one hidden: ```json { "success": true, "data": [ { "id": 32, "pageId": 20, "code": "01.big_with_text", "name": "Cover with changing background images", "active": false, "meta": { "LID": "20", "FAVORITE_META": "Array", "CREATED_BY_ID": "1", "DATE_CREATE": "10/12/2026 02:16:49 pm", "MODIFIED_BY_ID": "1", "DATE_MODIFY": "10/12/2026 02:16:49 pm", "SITE_TYPE": "PAGE", "LANDING_TITLE": "", "LANDING_TPL_CODE": "", "SITE_TPL_CODE": "", "XML_ID": "", "DESIGNER_MODE": "" }, "version": "draft" }, { "id": 30, "pageId": 20, "code": "03.1.three_cols_big_with_text_and_titles", "name": "Three-column full-width text on a colored background", "active": true, "meta": { "LID": "20", "FAVORITE_META": "Array", "CREATED_BY_ID": "1", "DATE_CREATE": "10/12/2026 02:16:48 pm", "MODIFIED_BY_ID": "1", "DATE_MODIFY": "10/12/2026 02:16:48 pm", "SITE_TYPE": "PAGE", "LANDING_TITLE": "", "LANDING_TPL_CODE": "", "SITE_TPL_CODE": "", "XML_ID": "", "DESIGNER_MODE": "" }, "version": "draft" }, { "id": 34, "pageId": 20, "code": "03.1.three_cols_big_with_text_and_titles", "name": "Three-column full-width text on a colored background", "active": true, "meta": { "LID": "20", "FAVORITE_META": "Array", "CREATED_BY_ID": "1", "DATE_CREATE": "10/12/2026 02:16:55 pm", "MODIFIED_BY_ID": "1", "DATE_MODIFY": "10/12/2026 02:16:55 pm", "SITE_TYPE": "PAGE", "LANDING_TITLE": "", "LANDING_TPL_CODE": "", "SITE_TPL_CODE": "", "XML_ID": "", "DESIGNER_MODE": "" }, "version": "draft" } ], "meta": { "version": "draft", "count": 3 } } ``` Request `GET /v1/pages/20/blocks?content=true`, showing two of the three blocks. The hidden block has `content` equal to `null`: ```json { "success": true, "data": [ { "id": 32, "pageId": 20, "code": "01.big_with_text", "name": "Cover with changing background images", "active": false, "meta": { "LID": "20", "FAVORITE_META": "Array", "CREATED_BY_ID": "1", "DATE_CREATE": "10/12/2026 02:16:49 pm", "MODIFIED_BY_ID": "1", "DATE_MODIFY": "10/12/2026 02:16:49 pm", "SITE_TYPE": "PAGE", "LANDING_TITLE": "", "LANDING_TPL_CODE": "", "SITE_TPL_CODE": "", "XML_ID": "", "DESIGNER_MODE": "" }, "content": null, "css": [], "js": [], "version": "draft" }, { "id": 34, "pageId": 20, "code": "03.1.three_cols_big_with_text_and_titles", "name": "Three-column full-width text on a colored background", "active": true, "meta": { "LID": "20", "FAVORITE_META": "Array", "CREATED_BY_ID": "1", "DATE_CREATE": "10/12/2026 02:16:55 pm", "MODIFIED_BY_ID": "1", "DATE_MODIFY": "10/12/2026 02:16:55 pm", "SITE_TYPE": "PAGE", "LANDING_TITLE": "", "LANDING_TPL_CODE": "", "SITE_TPL_CODE": "", "XML_ID": "", "DESIGNER_MODE": "" }, "content": "

Hello

", "css": [], "js": [], "version": "draft" } ], "meta": { "version": "draft", "count": 3 } } ``` ## Error response example 404 — page not found: ```json { "success": false, "error": { "code": "ENTITY_NOT_FOUND", "message": "No such landing page, or it is not visible to this key. A knowledge-base, group or vibe page also needs `?scope=`." } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 400 | `INVALID_PAGE_ID` | `pageId` is not a positive integer | | 400 | `INVALID_VERSION` | `version` is neither `draft` nor `published` | | 400 | `INVALID_SCOPE` | `scope` is not one of `KNOWLEDGE`, `GROUP`, `MAINPAGE` | | 400 | `INVALID_PARAMS` | Bitrix24 rejected the request: a required parameter is missing | | 400 | `WRONG_PATH` | The request was sent to `/v1/blocks` without a page. The message lists the correct paths | | 404 | `ENTITY_NOT_FOUND` | The page does not exist or is not visible to the key owner. A knowledge-base page, a workgroup page or a main page is not found without the `scope` parameter | | 413 | `RESPONSE_TOO_LARGE` | The response exceeds 5 MB. Read the page without `content=true` | | 502 | `BLOCK_LIST_UNCONFIRMED` | Bitrix24 did not return the block list. Retry the request | | 403 | `BITRIX_ACCESS_DENIED` | The employee the key was issued for has no access to the page 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 **The draft and the published version hold different blocks.** Adding, changing and deleting blocks modify the page draft. A visitor sees the changes only after the page is published with `POST /v1/pages/:id/publication`. After publication, blocks of the published version have their own IDs that differ from the draft IDs. Write methods accept only draft IDs: an ID taken from a `version=published` response is rejected with `404 BLOCK_NOT_IN_DRAFT`. ## See also - [Add a block](/docs/entities/pages/blocks/create) - [Change block content](/docs/entities/pages/blocks/update) - [Delete a block](/docs/entities/pages/blocks/delete) - [Restore a block](/docs/entities/pages/blocks/restore) - [Block catalog](/docs/entities/pages/catalog) - [Read a page block](/docs/entities/pages/block-get) - [List pages](/docs/entities/pages/list) - [Pages](/docs/entities/pages)