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

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

Rebuild a card set

PUT /v1/pages/:pageId/blocks/:blockId/cards

Rebuilds a block's card set from source cards and, in the same call, sets the node content of the new cards.

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. A block of another page returns 404
Parameterscope (query) Typestring Requiredno DescriptionInternal landing area: KNOWLEDGE — knowledge base, GROUP — workgroup knowledge base, MAINPAGE — main page. Omit for a regular site

Request fields (body)

Field Type Required Description
Fieldselector Typestring Requiredyes DescriptionCard set selector without @N, for example .landing-block-card. This method takes no index. Set selectors are the keys of the cards object in the GET /v1/pages/:pageId/blocks/:blockId/content response
Fieldsource Typearray Requiredyes DescriptionSources of the new cards, in order: after the write, the set contains one card per element. An empty array is not accepted
Fieldsource[].type Typestring Requiredno Descriptioncard — a copy of a card from the current set, preset — a card preset from the block manifest. Defaults to card
Fieldsource[].value Typenumber | string Requiredno DescriptionFor card — the zero-based index of a card in the current set. For preset — the preset key from cards.<selector>.presets in the GET /v1/block-repository/:code/manifest response, or the position in it for a presets array. The block code is data.code in the GET /v1/pages/:pageId/blocks/:blockId response. Defaults to 0
Fieldvalues Typeobject Requiredyes DescriptionNode content after the rebuild. Top-level keys are arbitrary edit group names. Inside a group, the key is a node selector with an index, and the value is the new content
Fieldvalues.<group>.<node>@N Typestring | number | object Requiredyes DescriptionNode content. N is the position among all nodes with this selector in the block after the rebuild, not within the card. A text node accepts a string, an integer or an object with a text field. null is not accepted. Node selectors are the keys of the nodes object in the GET /v1/pages/:pageId/blocks/:blockId/content response

Examples

The block has the cards First and Second. The request keeps both, adds a third one as a copy of the second, and names it Third.

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selector":".landing-block-card","source":[{"type":"card","value":0},{"type":"card","value":1},{"type":"card","value":1}],"values":{"third":{".landing-block-node-title@2":"Third"}}}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"selector":".landing-block-card","source":[{"type":"card","value":0},{"type":"card","value":1},{"type":"card","value":1}],"values":{"third":{".landing-block-node-title@2":"Third"}}}'

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards", {
  method: "PUT",
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card", "source": [{"type": "card", "value": 0}, {"type": "card", "value": 1}, {"type": "card", "value": 1}], "values": {"third": {".landing-block-node-title@2": "Third"}}}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards", {
  method: "PUT",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card", "source": [{"type": "card", "value": 0}, {"type": "card", "value": 1}, {"type": "card", "value": 1}], "values": {"third": {".landing-block-node-title@2": "Third"}}}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.cards Typeobject DescriptionBlock cards after the write. The key is the set selector, the value is the array of the set's cards in order
Fielddata.cards.<selector>[].index Typenumber DescriptionCurrent zero-based position of the card in the set
Fielddata.cards.<selector>[].content Typestring DescriptionCard HTML

Response example

JSON 
{
  "success": true,
  "data": {
    "cards": {
      ".landing-block-card": [
        {
          "index": 0,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">First</h3></div>"
        },
        {
          "index": 1,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Second</h3></div>"
        },
        {
          "index": 2,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Third</h3></div>"
        }
      ]
    }
  }
}

Error response example

400 — source contains the index of a card that is not in the current set:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "source card index does not exist."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionsource card index does not exist. — source contains the index of a card that is not in the current set
HTTP400 CodeINVALID_PARAMS Descriptionsource preset does not exist in the block manifest. — the block manifest has no preset with this key
HTTP400 CodeINVALID_PARAMS DescriptionEach source needs a card index or a preset key and type card or preset. — a source element is not an object, contains a field other than type and value, type is not card or preset, or value does not match the type
HTTP400 CodeINVALID_PARAMS Descriptionselector must address an existing card set. — the block has no set with this selector or the set is empty
HTTP400 CodeINVALID_PARAMS Descriptionselector must omit the card index; DELETE uses the index path parameter. — selector contains @N
HTTP400 CodeINVALID_PARAMS Descriptionselector has no card parent. — the cards of the set have no parent element
HTTP400 CodeINVALID_PARAMS DescriptionEach values entry must map node selectors with @index to content. — a group in values is not an object or is an empty object
HTTP400 CodeINVALID_PARAMS Descriptionvalues node selectors need a non-negative node index. — a node selector has no @N, or N is not a non-negative integer
HTTP400 CodeINVALID_PARAMS Descriptionvalues references a node absent from the rebuilt block. — the node is not in the block manifest, or after the rebuild there are fewer than N + 1 nodes with this selector
HTTP400 CodeINVALID_PARAMS DescriptionNode content cannot be null: Bitrix24 ignores it. — the node content is null
HTTP400 CodeINVALID_PARAMS DescriptionText nodes require a string, integer, or an object with text. — a text node received something other than a string or an integer: true, false, a fractional number, an array, or an object whose text is neither a string nor an integer
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionsource must be a non-empty array and values must be an object. — source is missing or empty, or values is missing or not an object
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionselector is required. — selector is missing, empty or whitespace-only
HTTP400 CodeINVALID_PARAMS DescriptionpageId and blockId must be positive safe integers. — pageId or blockId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionBody must be a JSON object. — the body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionBody contains an unsupported field. — the body contains a field other than selector, source and values
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionPage, block or card not found. — the block does not belong to page pageId or does not exist
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionExpanded card HTML exceeds 8 MiB. — the combined markup of the cards from source exceeds 8 MiB. The request is rejected before the write
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not confirm the card action. — Bitrix24 did not confirm the write
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not return cards after the action. — after the write, Bitrix24 did not return the block content
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not persist the requested card count. — the card count after the write does not match the length of source
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not persist the rebuilt cards. — the rebuild was supposed to change the block, but the markup stayed the same
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not persist the requested node text. — the node text from values was not saved
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the action. The error text comes from Bitrix24
HTTP502 CodeBITRIX_ERROR DescriptionBitrix24 returned invalid or oversized card content. — the block markup cannot be parsed or the cards exceed 8 MiB
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is rejected before Bitrix24 is called
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 user the key is issued for has no permission to edit the page
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key in X-Api-Key is not found or has been revoked
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not available 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
HTTP429 CodeRATE_LIMITED DescriptionThe Bitrix24 request limit is exceeded. Retry the request in 1-2 seconds
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 did not respond or returned a server error
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • A rebuild replaces the entire content of the card parent. Elements next to the cards that are not cards themselves, and other sets inside the same parent, are removed. To change a single card, use Clone a block card, Remove a card by index and Edit block text and images.
  • Validation runs before the write. An unknown selector, a nonexistent source and a node outside the rebuilt block are rejected before the block changes.
  • A failure after the write does not undo the rebuild. The 422, 502 and 503 responses do not mean the set stayed the same. Before retrying, re-read the block via GET /v1/pages/:pageId/blocks/:blockId/content: the source indexes refer to the set before the write.

See also