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

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

Replace block markup

PATCH /v1/pages/:pageId/blocks/:blockId

Replaces the entire HTML markup of a block on a landing page: the new markup is not merged with the current one.

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
ParameterblockId (path) Typenumber Requiredyes DescriptionBlock ID in the page draft. List: GET /v1/pages/:pageId/blocks, which reads the draft by default. IDs from ?version=published and IDs of blocks in the trash are not accepted
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. Omit it for a regular site page

Request fields (body)

Field Type Required Description
Fieldcontent Typestring Requiredyes DescriptionNew HTML markup of the block. Fully replaces the current markup
Fielddesigned Typeboolean Requiredno DescriptionFlag for a block with its own design. Defaults to false. Also accepts the strings "true", "false", "1", "0" and the numbers 1, 0. A block that does not support this flag responds with 422 BLOCK_DESIGN_NOT_SUPPORTED

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

const { success, data } = await res.json()
console.log('Publish with:', data.publishWith)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe updated block and how to publish it
Fielddata.id Typenumber DescriptionID of the updated block, the same as in the path
Fielddata.version Typestring DescriptionPage version in which the block was changed. Always draft
Fielddata.published Typeboolean DescriptionWhether the change is published. Always false
Fielddata.publishWith Typestring DescriptionThe call that publishes the page together with the change, with the page ID filled in. To publish only this block, see Publish a block

Response example

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

Error response example

404 — no block with this ID in the page draft:

JSON 
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's draft. Ids come from GET /v1/pages/{pageId}/blocks, which reads the draft by default; ids from the published version are not accepted here."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_BLOCK_CONTENT Descriptioncontent is missing or is not a string
HTTP400 CodeINVALID_DESIGNED Descriptiondesigned is not a boolean value
HTTP400 CodeINVALID_PAGE_ID DescriptionpageId in the path is not a positive integer
HTTP400 CodeINVALID_BLOCK_ID DescriptionblockId 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 CodeBLOCK_NOT_IN_DRAFT DescriptionThe block is not in the page draft: the ID does not exist, the block was moved to the trash, or the ID was taken from the published version
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
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe draft check found the block, but when replacing the markup Bitrix24 responded that the block is not on the page
HTTP422 CodeBLOCK_DESIGN_NOT_SUPPORTED Descriptiondesigned: true was passed, but the block does not support the designed flag. Retry the request without designed
HTTP502 CodeBLOCK_LIST_UNCONFIRMED DescriptionBitrix24 did not return the page draft: the block's presence was not checked and the markup was not changed
HTTP502 CodeBLOCK_CONTENT_UPDATE_UNCONFIRMED DescriptionBitrix24 did not confirm the markup replacement
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

The block wrapper is preserved. After the replacement, reading GET /v1/pages/:pageId/blocks?content=true returns the new markup inside the original <div id="b<id>" class="block-wrapper …"> element.

See also