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

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

Remove a card by index

DELETE /v1/pages/:pageId/blocks/:blockId/cards/:index

Removes one card from a block's card set by its current position. The removal is irreversible.

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
Parameterindex (path) Typenumber Requiredyes DescriptionCurrent zero-based position of the card in the set. Take it from data.cards in the latest response from a card method. Before the first write, the position is the ordinal number of the element with the set class in the html of the GET /v1/pages/:pageId/blocks/:blockId/content response
Parameterselector (query) Typestring Requiredyes DescriptionCard set selector without @N, for example .landing-block-card. Set selectors are the keys of the cards object in the GET /v1/pages/:pageId/blocks/:blockId/content response
Parameterscope (query) Typestring Requiredno DescriptionInternal landing area: KNOWLEDGE — knowledge base, GROUP — workgroup knowledge base, MAINPAGE — main page. Omit for a regular site

The request has no body.

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/cards/1?selector=.landing-block-card", {
  method: "DELETE",
  headers: {"X-Api-Key": "YOUR_API_KEY"},
})
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/1?selector=.landing-block-card", {
  method: "DELETE",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN"},
})
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 removal. The key is the set selector, the value is the array of the set's cards in order. After the last card is removed, the array is empty
Fielddata.cards.<selector>[].index Typenumber DescriptionCurrent zero-based position of the card in the set
Fielddata.cards.<selector>[].content Typestring DescriptionCard HTML

Response example

The block had the cards First and Second. The card with index 1 is removed:

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

Error response example

404 — the set has no card with this index, the block has no such set, or the block belongs to another page:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Page, block or card not found."
  }
}

Errors

HTTP Code Description
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 index. Same response if the block does not exist
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionselector is required. — selector is missing from the query, empty or whitespace-only
HTTP400 CodeINVALID_PARAMS Descriptionselector must omit the card index; DELETE uses the index path parameter. — selector contains @N. The index goes in the path only
HTTP400 CodeINVALID_PARAMS Descriptionindex must be a non-negative safe integer. — index is not a non-negative integer
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. — a body was sent that is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionBody contains an unsupported field. — a body with fields was sent
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 card count did not drop by one 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

  • A stale index removes a neighboring card. Positions shift after every write, and a card has no permanent ID. An index from an old response already points at a different card, and the method returns no error.
  • The last card can be removed. The set becomes empty, and the block stays on the page. The card methods cannot bring a card back into an empty set: cloning and adding need a reference card and return 404, rebuilding returns 400.
  • A failure after the write does not undo the removal. The 422, 502 and 503 responses do not mean the card is still there. Before retrying, re-read the block via GET /v1/pages/:pageId/blocks/:blockId/content: a retry with the same index removes the next card.

See also