## 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](/docs/entities/pages/list). |
| `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

```bash
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

```bash
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](/docs/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.