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

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

Change block text and images

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

Changes the content of a page block's nodes: text, images and links.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
ParameterblockId (path) Typenumber Requiredyes DescriptionID of a block on this page. List: GET /v1/pages/:pageId/blocks
Parameterscope (query) Typestring Requiredno DescriptionSite area: KNOWLEDGE — knowledge base, GROUP — workgroup pages, MAINPAGE — main pages. Omit the parameter for pages of all other sites

Request fields (body)

Field Type Required Description
Fieldnodes Typeobject Requiredyes DescriptionA "selector → value" object with at least one pair. A selector is .class or .class@N, where N is a zero-based index among the nodes with this class. Without @N the value is written to every node with this class. The available selectors and the type of each node are in the nodes field of the GET /v1/pages/:pageId/blocks/:blockId/content response
Fieldnodes.<selector> — text node Typestring | integer | object Required— DescriptionA string, an integer, or an object {"text": "…"} with a string or an integer in text. A fractional number is rejected
Fieldnodes.<selector> — image Typeobject Required— Descriptionsrc — image URL, alt — alternative text. The URL of your own image is returned in the data.url field of the Upload an image to a block method
Fieldnodes.<selector> — link Typeobject Required— Descriptionhref — link URL, text — link text, target — where to open the link, _blank opens a new tab

An empty object or an empty array is not accepted as a value. The keys attrs, dynamicState, dynamicBlock and dynamicParams are accepted neither as a selector nor inside a value.

Values for an image and for a link:

JSON 
{
  "nodes": {
    ".landing-block-node-img": { "src": "https://cdn.example.com/landing/2e8/pixel.png", "alt": "Cover" },
    ".landing-block-node-button": { "href": "https://example.com/sale", "text": "Buy now", "target": "_blank" }
  }
}

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/nodes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": {
      ".landing-block-node-title": "Spring sale"
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/nodes" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": {
      ".landing-block-node-title": "Spring sale"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/nodes', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nodes: {
      '.landing-block-node-title': 'Spring sale',
    },
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/nodes', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nodes: {
      '.landing-block-node-title': 'Spring sale',
    },
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionBlock ID
Fielddata.pageId Typenumber DescriptionPage ID
Fielddata.anchor Typestring DescriptionBlock anchor. An automatic anchor has the form b<id>, for example b7
Fielddata.content Typestring DescriptionThe full block HTML, read back after the change
Fielddata.nodes Typeobject DescriptionEmpty object. The block state is in content
Fielddata.styles Typeobject DescriptionEmpty object. The block state is in content
Fielddata.attrs Typeobject DescriptionEmpty object. The block state is in content
Fielddata.cards Typeobject DescriptionEmpty object. The block state is in content
Fielddata.active Typeboolean DescriptionWhether the block is active

Response example

The paragraph text in content is shortened with an ellipsis, and the markup is unchanged.

JSON 
{
  "success": true,
  "data": {
    "id": 7,
    "pageId": 42,
    "anchor": "b7",
    "content": "<div id=\"block7\" data-id=\"7\" class=\"block-wrapper block-27-one-col-fix-title-and-text-2\"><section class=\"landing-block js-animation g-pt-30 g-pb-30\">\r\n\t<div class=\"landing-block-node-text-container container g-max-width-container\">\r\n\t\t<h2 class=\"landing-block-node-title js-animation fadeIn g-mb-20 g-color\">Spring sale</h2>\r\n\t\t<div class=\"landing-block-node-text js-animation g-mb-20 g-pb-1 g-color\">\r\n\t\t\tSed feugiat porttitor nunc, non dignissim ipsum vestibulum in. …\r\n\t\t</div>\r\n\t</div>\r\n</section></div>",
    "nodes": {},
    "styles": {},
    "attrs": {},
    "cards": {},
    "active": true
  }
}

Error response example

400 — a text node received an object without a text field:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Text nodes require a string, integer or an object with text"
  }
}

Errors

HTTP Code Marker in error.message Description
HTTP400 CodeINVALID_PARAMS Marker in error.messagepageId and blockId must be positive safe integers DescriptionpageId or blockId is not a positive integer
HTTP400 CodeINVALID_SCOPE Marker in error.messagescope must be KNOWLEDGE, GROUP or MAINPAGE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP400 CodeMISSING_REQUIRED_FIELDS Marker in error.messageRequired fields: nodes DescriptionThe body has no nodes field
HTTP400 CodeMISSING_REQUIRED_FIELDS Marker in error.messageA JSON object is required DescriptionThe body is not a JSON object
HTTP400 CodeMISSING_REQUIRED_FIELDS Marker in error.messagenodes must be a non-empty selector map Descriptionnodes is an empty object or not an object
HTTP400 CodeINVALID_PARAMS Marker in error.messageUnexpected body field DescriptionThe body has a field other than nodes
HTTP400 CodeINVALID_PARAMS Marker in error.messageSelectors must be .class or .class@N DescriptionA selector is not in the .class or .class@N format, including the service key attrs in place of a selector
HTTP400 CodeINVALID_PARAMS Marker in error.messageService node fields are not accepted DescriptionThe value object has an attrs, dynamicState, dynamicBlock or dynamicParams key
HTTP400 CodeINVALID_PARAMS Marker in error.messageNode values must not be empty objects or arrays DescriptionThe value is an empty object or an empty array
HTTP400 CodeINVALID_PARAMS Marker in error.messageEach node value must be a string, integer, object or array DescriptionThe value is a fractional number, null or a boolean
HTTP400 CodeINVALID_PARAMS Marker in error.messageText nodes require a string, integer or an object with text DescriptionThe text node value is neither a string, an integer, nor an object with a string or an integer in text
HTTP400 CodeINVALID_PARAMS Marker in error.messageUnknown selector or index. Available selectors: … DescriptionThe block has no such selector, or the @N index exceeds the number of nodes with this class. The message lists the available selectors
HTTP401 CodeTOKEN_MISSING Marker in error.message— DescriptionThe API key has no Bitrix24 access tokens
HTTP403 CodeSCOPE_DENIED Marker in error.message— DescriptionThe key has no landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY Marker in error.message— DescriptionThe key is read-only. The request is rejected before the Bitrix24 account is called
HTTP404 CodeENTITY_NOT_FOUND Marker in error.messagePage or block not found DescriptionThe page does not exist, the block does not exist, or the block belongs to another page
HTTP404 CodeENTITY_NOT_FOUND Marker in error.message— DescriptionThe change was accepted, but the block could not be read back after it
HTTP409 CodeLANDING_MODULE_NOT_ENABLED Marker in error.message— DescriptionThe Sites module is not enabled on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED Marker in error.message— DescriptionA self-hosted Bitrix24 portal moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook
HTTP422 CodeBITRIX_ERROR Marker in error.messageBitrix24 did not confirm the block operation DescriptionBitrix24 did not confirm the block change

Full list of common API errors — Errors.

Known specifics

  • Scripts and event handlers are neutralized without an error. The string Hi<script>alert(1)</script><b onclick="x()">bold</b> gets a 200 response but is saved modified: Hi<sc ript="">alert(1)<b oncl="" ick="x()">bold</b></sc>. script tags and on* attributes stop working, and the text stays on the page in modified form. Check what was actually saved in data.content.

See also