لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/pages/blocks/create.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Add a block to a page

POST /v1/pages/:pageId/blocks

Adds a block from the Bitrix24 account block catalog to a landing page, with the catalog markup or with your own.

Fields are passed flat at the root of the JSON, without a fields wrapper. Working with pages and their blocks is covered in Pages.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
Parameterscope (query) Typestring Requiredno DescriptionBitrix24 section the page belongs to: KNOWLEDGE for the knowledge base, GROUP for a workgroup knowledge base, MAINPAGE for the main page. Not passed for a page of a regular site

Request fields (body)

Field Type Required Description
Fieldcode Typestring Requiredyes DescriptionBlock code from the catalog. Catalog: GET /v1/block-repository. The code is the item key in the section's items
FieldafterId Typenumber Requiredno DescriptionID of a block on this page after which the new block is placed. List: GET /v1/pages/:pageId/blocks. Without this field, the new block is placed first on the page
Fieldactive Typeboolean Requiredno DescriptionBlock visibility. false creates the block hidden. By default the block is visible. Also accepts the strings "true", "false", "1", "0" and the numbers 1, 0
Fieldcontent Typestring Requiredno DescriptionHTML markup of the block instead of the catalog markup. Without this field, the block gets the catalog markup

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/20/blocks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "03.1.three_cols_big_with_text_and_titles",
    "afterId": 30,
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Hello</h2></div></section>"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/20/blocks" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "03.1.three_cols_big_with_text_and_titles",
    "afterId": 30,
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Hello</h2></div></section>"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: '03.1.three_cols_big_with_text_and_titles',
    afterId: 30,
    content: '<section class="landing-block"><div class="container"><h2>Hello</h2></div></section>',
  }),
})

const { success, data } = await res.json()
console.log('Block ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: '03.1.three_cols_big_with_text_and_titles',
    afterId: 30,
    content: '<section class="landing-block"><div class="container"><h2>Hello</h2></div></section>',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created block and how to publish it
Fielddata.id Typenumber DescriptionID of the created block in the page draft. Pass it to PATCH /v1/pages/:pageId/blocks/:blockId and DELETE /v1/pages/:pageId/blocks/:blockId
Fielddata.version Typestring DescriptionPage version the block was added to. Always draft
Fielddata.published Typeboolean DescriptionWhether the change is published. Always false
Fielddata.publishWith Typestring DescriptionThe call that publishes the page together with the new block, with the page ID filled in

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 32,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication"
  }
}

Error response example

422 — the block code is not in the catalog:

JSON 
{
  "success": false,
  "error": {
    "code": "BLOCK_CANT_BE_ADDED",
    "message": "Bitrix24 refused to add this block. Check that `code` is a code from GET /v1/block-repository."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_BLOCK_CODE Descriptioncode is missing or is an empty string
HTTP400 CodeINVALID_AFTER_ID DescriptionafterId is not a positive integer
HTTP400 CodeINVALID_ACTIVE Descriptionactive is not a boolean value
HTTP400 CodeINVALID_CONTENT Descriptioncontent is not a string
HTTP400 CodeINVALID_PAGE_ID DescriptionpageId in the path is not a positive integer
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the request: a required parameter is missing
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe page does not exist or is not visible to the key. A knowledge base, workgroup or main page requires the scope parameter
HTTP422 CodeBLOCK_CANT_BE_ADDED DescriptionBitrix24 refused to add the block: the code value is not in the catalog
HTTP422 CodeBLOCK_WRONG_VERSION DescriptionThe catalog block requires a newer version of the sites module than the one installed on the Bitrix24 portal
HTTP502 CodeBLOCK_ADD_UNCONFIRMED DescriptionBitrix24 did not return the ID of the new block: creation is not confirmed
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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors: Errors.

Known specifics

Markup is returned in a wrapper. Reading GET /v1/pages/:pageId/blocks?content=true returns the markup from content inside a <div id="b<id>" class="block-wrapper block-<code>"> element. In the wrapper class, dots and underscores of the block code are replaced with hyphens: for 03.1.three_cols_big_with_text_and_titles it is block-03-1-three-cols-big-with-text-and-titles.

A non-existent afterId is not rejected. If the page has no block with this ID, the block is still created with a 201 response, but it lands somewhere on the page other than first or last. Before the call, take afterId from the block list, and after the call, check the new block's position with the same list.

See also