For AI agents: markdown of this page — /docs-content-en/entities/pages/blocks/update.md documentation index — /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
pageId (path) number yes Page ID. List: GET /v1/pages
blockId (path) number yes Block 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
scope (query) string no Bitrix24 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
content string yes New HTML markup of the block. Fully replaces the current markup
designed boolean no Flag 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
success boolean Always true on success
data object The updated block and how to publish it
data.id number ID of the updated block, the same as in the path
data.version string Page version in which the block was changed. Always draft
data.published boolean Whether the change is published. Always false
data.publishWith string The 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
400 MISSING_BLOCK_CONTENT content is missing or is not a string
400 INVALID_DESIGNED designed is not a boolean value
400 INVALID_PAGE_ID pageId in the path is not a positive integer
400 INVALID_BLOCK_ID blockId in the path is not a positive integer
400 INVALID_SCOPE scope is not KNOWLEDGE, GROUP or MAINPAGE
400 INVALID_PARAMS Bitrix24 rejected the request: a required parameter is missing
404 BLOCK_NOT_IN_DRAFT The 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
404 ENTITY_NOT_FOUND The page does not exist or is not visible to the key. A knowledge base, workgroup or main page requires the scope parameter
404 ENTITY_NOT_FOUND The draft check found the block, but when replacing the markup Bitrix24 responded that the block is not on the page
422 BLOCK_DESIGN_NOT_SUPPORTED designed: true was passed, but the block does not support the designed flag. Retry the request without designed
502 BLOCK_LIST_UNCONFIRMED Bitrix24 did not return the page draft: the block's presence was not checked and the markup was not changed
502 BLOCK_CONTENT_UPDATE_UNCONFIRMED Bitrix24 did not confirm the markup replacement
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
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The 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