Add a card with HTML

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

Clones the source and replaces the new card HTML. Bitrix24 sanitizes unsafe HTML. Keep the block class structure in the card markup. The @N indexes shift.

Requires the landing scope; READONLY keys receive 403 before mutation. Page-scoped actions check that the block belongs to the page.

Optional query scope: KNOWLEDGE, GROUP or MAINPAGE for that page context; omit for a regular site. IDs must be positive safe integers.

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>"}'

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)

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 — 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

JSON

{
  "success": true,
  "data": {
    "cards": {
      ".landing-block-card": [
        {
          "index": 0,
          "content": "<div class=\"landing-block-card\">Example</div>"
        }
      ]
    }
  }
}

A refusal after mutation does not undo the Bitrix24 action. On 422/502 after dispatch, read the block first; retrying clone/add can create another card.

Errors

HTTP	Code
400	INVALID_PARAMS / MISSING_REQUIRED_FIELDS / INVALID_SCOPE
401	MISSING_API_KEY / INVALID_API_KEY / TOKEN_MISSING
403	SCOPE_DENIED / WRITE_BLOCKED_READONLY_KEY / BITRIX_ACCESS_DENIED
404	ENTITY_NOT_FOUND
409	PORTAL_ADDRESS_CHANGED / LANDING_MODULE_NOT_ENABLED
422	BITRIX_ERROR / BITRIX_NO_EFFECT
429	RATE_LIMITED
502	BITRIX_ERROR
503	SERVICE_UNAVAILABLE