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

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

Change a block node tag

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

Changes the HTML tag of a block node on a site page, for example the heading level from h2 to h3. The node's text, classes and attributes stay the same.

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 — home pages. Omit the parameter for pages of all other sites

Request fields (body)

Field Type Required Description
Fieldtags Typeobject Requiredyes DescriptionAn object of the form "selector → tag". Must not be empty. The body has no other fields
Fieldtags.<selector> Typestring Requiredyes DescriptionThe key is a node selector .class or .class@N, where N is a zero-based index among the nodes with that class. Without @N, the tag changes on all nodes with that class. Valid selectors are the keys of nodes in the response of GET /v1/pages/:pageId/blocks/:blockId/content. The value is a non-empty string with the tag name, for example h3

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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; 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<h3 class=\"landing-block-node-title g-color-red g-mb-20\">Spring sale</h3>\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 — an empty string was passed for a selector instead of a tag:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Each tag must be a non-empty string"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe value for a selector is not a string, or is an empty string
HTTP400 CodeINVALID_PARAMS DescriptionThe block manifest lists allowed tags for the node, and the passed tag is not among them. The node manifest is the nodes field of the GET /v1/pages/:pageId/blocks/:blockId/content response
HTTP400 CodeINVALID_PARAMS DescriptionThe selector is not among the block's nodes, or the @N index exceeds the number of nodes with that class. The message lists the available selectors
HTTP400 CodeINVALID_PARAMS DescriptionThe selector is not in the .class or .class@N format. Service keys are not accepted in place of a selector
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than tags
HTTP400 CodeINVALID_PARAMS DescriptionpageId or blockId is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body is not a JSON object, it has no tags field, or tags is an empty object
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe page does not exist, the block does not exist, or the block belongs to another page
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe change was accepted, but the block could not be read back afterwards
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not enabled on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED DescriptionA self-hosted Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the block change
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is refused before any call to the Bitrix24 account
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the landing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 access tokens

Full list of common API errors — Errors.

Known specifics

  • If the manifest does not restrict the node's tags, any tag is accepted. The link button .landing-block-node-button became a heading after its tag was changed from a to h2: the href and target attributes remained in the markup, but the link no longer works in the browser. Before replacing the tag of a link, check what the node is for.

See also