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

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

Add a card with HTML

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

Adds a new card with its own markup to a block's card set.

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 with the index of the reference card: with .landing-block-card@0, the new card goes after the first one. Set selectors are the keys of the cards object in the GET /v1/pages/:pageId/blocks/:blockId/content response. Without @N, the new card goes to the start of the set, at position 0
Fieldcontent Typestring Requiredyes DescriptionHTML of the new card. The root element carries the set class, and the elements inside it carry the same node classes as the block's cards: subsequent calls find the card by these classes. The markup is sanitized: <script> tags are neutralized

Examples

curl — personal key

Terminal 
curl -X POST "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@0","content":"<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}'

curl — OAuth application

Terminal 
curl -X POST "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@0","content":"<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}'

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card@0", "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}),
})
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: "POST",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card@0", "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}),
})
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. This is the N in @N for the next call
Fielddata.cards.<selector>[].content Typestring DescriptionCard HTML after sanitization

Response example

The block had the cards First and Second. The new card went after the first one, at position 1:

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\">Example</h3></div>"
        },
        {
          "index": 2,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Second</h3></div>"
        }
      ]
    }
  }
}

Error response example

400 — content is missing or empty:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "content must be non-empty HTML."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptioncontent must be non-empty HTML. — content is missing or whitespace-only
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionselector is required. — selector is missing, empty or whitespace-only
HTTP404 CodeENTITY_NOT_FOUND DescriptionPage, block or card not found. — the block does not belong to page pageId, the block has no set with this selector, or the set has no card with index @N. Same response if the block does not exist
HTTP400 CodeINVALID_PARAMS Descriptionselector index must be a non-negative safe integer. — the value after @ is not a non-negative integer, the selector contains more than one @, or nothing precedes @
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 and content
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
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 block markup did not change after the write
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

  • Indexes shift after every write. Cards have no permanent ID: the N in @N is the position in the set at the time of the call. Before the next operation, take the indexes from data.cards of the latest response.
  • A failure after the write does not undo the addition. The 422, 502 and 503 responses do not mean the card was not added. Before retrying, re-read the block via GET /v1/pages/:pageId/blocks/:blockId/content: a retry can add one more card.
  • The response is read from the draft. The cards in the response come from the page draft, including unpublished edits.

See also