## Delete a block

`DELETE /v1/pages/:pageId/blocks/:blockId`

Moves a page block to that page's trash. Deletion is reversible: while the block is in the trash, you can return it to the page with the restore method.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `pageId` (path) | number | yes | Page ID. List: [`GET /v1/pages`](/docs/entities/pages/list) |
| `blockId` (path) | number | yes | Block ID from the page draft. List: [`GET /v1/pages/:pageId/blocks`](/docs/entities/pages/blocks/list) without the `version` parameter. Block IDs from the published version are not accepted here |
| `scope` (query) | string | no | Site type: `KNOWLEDGE` — knowledge base, `GROUP` — workgroup site, `MAINPAGE` — main page. Omit the parameter for pages of other sites |

## Examples

### curl — personal key

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/20/blocks/30" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/pages/20/blocks/30" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Block is in the trash, restore with:', body.data.restoreWith)
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Block is in the trash, restore with:', body.data.restoreWith)
}
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` — the block was moved to the trash |
| `data.id` | number | ID of the deleted block |
| `data.deleted` | boolean | Always `true`: the block is in the page's trash |
| `data.version` | string | Page version the call changed. Always `draft` — the draft |
| `data.published` | boolean | Always `false`: the published version of the page did not change |
| `data.publishWith` | string | Call that publishes the page draft, with the page ID filled in |
| `data.restoreWith` | string | Call that returns this block from the trash, with the page and block IDs filled in |

## Response example

```json
{
  "success": true,
  "data": {
    "id": 30,
    "deleted": true,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication",
    "restoreWith": "POST /v1/pages/20/blocks/30/restore"
  }
}
```

## Error response example

404 — the block is not in the page draft, for example, because it is already in the trash:

```json
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's draft. Ids come from GET /v1/pages/{pageId}/blocks, which reads the draft by default; ids from the published version are not accepted here."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PAGE_ID` | `pageId` is not a positive integer |
| 400 | `INVALID_BLOCK_ID` | `blockId` is not a positive integer |
| 400 | `INVALID_SCOPE` | `scope` is not one of `KNOWLEDGE`, `GROUP`, `MAINPAGE` |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the request: a required parameter is missing |
| 404 | `BLOCK_NOT_IN_DRAFT` | No block with this ID in the page draft: the block is already in the trash, the ID comes from the published version, or it does not exist |
| 404 | `ENTITY_NOT_FOUND` | The page does not exist or is not visible to the key. A knowledge base page, workgroup page or main page requires the `scope` parameter |
| 404 | `ENTITY_NOT_FOUND` | The draft check found the block, but when moving it to the trash Bitrix24 responded that the block is not on the page |
| 502 | `BLOCK_LIST_UNCONFIRMED` | Bitrix24 did not return the page draft, so the block could not be checked before deletion. The block is untouched |
| 502 | `BLOCK_DELETE_UNCONFIRMED` | Bitrix24 did not confirm the move to the trash. Before retrying, check the trash with a `?deleted=true` request |
| 403 | `BITRIX_ACCESS_DENIED` | The employee the key was issued for has no permissions on the page in Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The error text is in `message` |
| 403 | `SCOPE_DENIED` | The key lacks the `landing` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **A block in the trash drops out of the draft.** You cannot replace its markup via [`PATCH /v1/pages/:pageId/blocks/:blockId`](/docs/entities/pages/blocks/update) until it is restored: the response is `404 BLOCK_NOT_IN_DRAFT`. The block can be found in the list [`GET /v1/pages/:pageId/blocks?deleted=true`](/docs/entities/pages/blocks/list).
- **Retry after a lost response.** A repeated call for a block that is already in the trash returns `404 BLOCK_NOT_IN_DRAFT`, not success. To find out whether the first call worked, look for the block in the list with `?deleted=true`.
- **Irreversible deletion is a separate method.** This call only moves the block to the trash. To delete a block with no way to restore it, see [Permanently delete a block](/docs/entities/pages/blocks/purge).

## See also

- [Restore a block](/docs/entities/pages/blocks/restore)
- [List page blocks](/docs/entities/pages/blocks/list)
- [Permanently delete a block](/docs/entities/pages/blocks/purge)
- [Pages](/docs/entities/pages)
- [Errors](/docs/errors)