لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/pages/blocks/list.md فهرس التوثيق — /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
ParameterpageId (path) Typenumber Requiredyes Default— DescriptionPage ID. List: GET /v1/pages
Parameterversion (query) Typestring Requiredno Defaultdraft DescriptionPage version: draft is the draft, published is what a site visitor sees
Parameterdeleted (query) Typeboolean Requiredno Defaultfalse Descriptiontrue returns the blocks in the page's trash instead of the blocks on the page
Parametercontent (query) Typeboolean Requiredno Defaultfalse Descriptiontrue adds each block's content markup and its css and js includes. The response grows by the HTML of all blocks on the page
Parameterscope (query) Typestring Requiredno Default— DescriptionSite 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionPage blocks in the order they appear on the page. An empty array if the page has no blocks
Fielddata[].id Typenumber DescriptionBlock ID in the page version that was read
Fielddata[].pageId Typenumber DescriptionPage ID
Fielddata[].code Typestring DescriptionBlock code from the catalog. Catalog: GET /v1/block-repository
Fielddata[].name Typestring DescriptionBlock name in the Bitrix24 account language
Fielddata[].active Typeboolean Descriptionfalse means the block is hidden on the page
Fielddata[].meta Typeobject DescriptionService 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
Fielddata[].content Typestring | null DescriptionOnly with content=true. Block HTML including the outer wrapper <div id="b<id>" class="block-wrapper …">. null for a hidden block
Fielddata[].css Typearray DescriptionOnly with content=true. Stylesheets the block includes
Fielddata[].js Typearray DescriptionOnly with content=true. Scripts the block includes
Fielddata[].version Typestring DescriptionVersion the block was read from: draft or published
Fieldmeta.version Typestring DescriptionPage version the request read: draft or published
Fieldmeta.count Typenumber DescriptionNumber 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
HTTP400 CodeINVALID_PAGE_ID DescriptionpageId is not a positive integer
HTTP400 CodeINVALID_VERSION Descriptionversion is neither draft nor published
HTTP400 CodeINVALID_SCOPE Descriptionscope is not one of KNOWLEDGE, GROUP, MAINPAGE
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the request: a required parameter is missing
HTTP400 CodeWRONG_PATH DescriptionThe request was sent to /v1/blocks without a page. The message lists the correct paths
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe 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
HTTP413 CodeRESPONSE_TOO_LARGE DescriptionThe response exceeds 5 MB. Read the page without content=true
HTTP502 CodeBLOCK_LIST_UNCONFIRMED DescriptionBitrix24 did not return the block list. Retry the request
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe employee the key was issued for has no access to the page in Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request; the error text is in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the landing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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 and respond with 404 to an ID taken from a version=published response: replacing markup and moving to the trash return BLOCK_NOT_IN_DRAFT, while copy, move, move up, move down, hide, show and permanent deletion return ENTITY_NOT_FOUND.

See also