Permanently delete selected blocks

POST /v1/pages/:pageId/blocks/bulk-purge

Irreversibly deletes selected blocks and their files. All block and image parent IDs are checked before any write. Each deleted block is independently read back; survivors return 422 with error.blockIds. images unlinks files on blocks of this page that remain after deletion. Bitrix24 does not report image unlink results, so they cannot be confirmed.

Requires landing scope. A READONLY key receives 403 before calling Bitrix24. Changes affect the draft.

Request parameters

Field	Type	Required	Description
`pageId`	integer	yes	Source page from List pages.
`scope`	string	no	Query: KNOWLEDGE, GROUP, MAINPAGE; omit for ordinary sites.
`blockIds`	integer[]	yes	Non-empty list, maximum 50 IDs.
`images`	object[]	no	Maximum 50 {blockId, fileId}, positive IDs; blockId belongs to the page.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/bulk-purge" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blockIds": [31, 32]}'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/bulk-purge" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"blockIds": [31, 32]}'

JavaScript — personal key

javascript

const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/bulk-purge", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({"blockIds": [31, 32]})
});
const result = await response.json();

JavaScript — OAuth application

javascript

const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/bulk-purge", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"blockIds": [31, 32]})
});
const result = await response.json();

Response fields

Field	Type	Description
`success`	boolean	Successful response.
`data`	object	Operation result.
`data.pageId`	integer	Result page ID.
`data.deletedBlockIds`	integer[]	Block IDs confirmed absent.

Response

JSON

{
  "success": true,
  "data": {
    "pageId": 42,
    "deletedBlockIds": [
      31,
      32
    ]
  }
}

Errors

HTTP	Code	Reason
400	`INVALID_PARAMS`	Invalid ID, body or destination anchor.
400	`MISSING_REQUIRED_FIELDS`	Missing required field.
403	`SCOPE_DENIED / WRITE_BLOCKED_READONLY_KEY`	Missing landing or read-only key.
409	`LANDING_MODULE_NOT_ENABLED`	The Sites module is unavailable on the portal.
404	`ENTITY_NOT_FOUND`	Missing page or block does not belong to source page.
422	`BITRIX_ERROR / BITRIX_NO_EFFECT`	Bitrix24 refusal or unconfirmed result; do not blindly retry deletion.
400	`BLOCK_PURGE_LIMIT`	More than 50 blocks or images.

Common errors.

Each Bitrix24 response is bounded to 8 MiB; exceeding the cap returns 502. Do not blindly retry an unconfirmed action: copy may create another block and up/down will change the order again.