For AI agents: markdown of this page — /docs-content-en/entities/pages/blocks/list.md documentation index — /llms.txt

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
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

Terminal 
curl "https://vibecode.bitrix24.com/v1/pages/20/blocks" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
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
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 <div id="b<id>" class="block-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": "<div id=\"b34\" class=\"block-wrapper block-03-1-three-cols-big-with-text-and-titles\"><section class=\"landing-block\"><div class=\"container\"><h2>Hello</h2></div></section></div>",
      "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.

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