> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete a block

> Move a block to the trash. It can be restored for 30 days. Requires Update content.

Moves a block and its children to the trash. Requires **Update content**. You can restore it for 30 days.

**Authorization** `string` *required*

`Bearer <token>`. See [Tokens](https://developers.bottari.ai/auth/tokens.md).

**Bottari-Version** `string`

Optional. Only `2026-03-11` is accepted. Without it, the current version is used. A different value returns 400.

**id** `string` *required*

A block ID. A subpage, row, or database ID moves that subpage, row, or database to the trash.

## What moves with it

* Subpages and inline databases inside the block move to the trash too. They come back when you restore the block.
* A subpage or inline database that was deleted before this block stays deleted.
* If the block holds a subpage or database the integration can't write, the whole request returns 403 and nothing changes.

## Read a deleted block

| Request | Response |
| - | - |
| `GET /v1/blocks/{id}` | 200 with `in_trash: true`. Blocks inside it also return 200. |
| `GET /v1/blocks/{id}/children` | 404 |
| `PATCH` or `DELETE` on it | 400 `Can't edit block that is archived. You must unarchive the block before editing.` |
| `PATCH` or `DELETE` on a block inside it | 400 `Can't edit page on block with an archived ancestor. You must unarchive the ancestor before editing page.` |

These rules cover blocks deleted through this API, `in_trash: true`, Markdown edits, and `erase_content`. A block a person deleted in the app returns 404 and can't be restored through the API.

## Restore

| What was deleted | How to restore |
| - | - |
| A block | `PATCH /v1/blocks/{id}` with `{ "in_trash": false }` |
| A subpage or row | `PATCH /v1/pages/{id}` with `{ "in_trash": false }` |
| A database | `PATCH /v1/blocks/{id}` with `{ "in_trash": false }` |

* A restored block goes to the end of its parent. If the parent no longer exists, it goes to the end of the document.
* A block whose parent is also deleted can't be restored on its own. The response is 400.
* A subpage or database inside a deleted block can't be restored on its own either. Restore the block.
* If deleting one column left a single column, that list was removed. Restoring the column puts its blocks at the end of the document, and the response is the first of them.

## Response

The block object with `in_trash: true`. See [Retrieve a block](https://developers.bottari.ai/api-reference/blocks/retrieve.md).

## Errors

| Status | `code` | Cause |
| - | - | - |
| 400 | `validation_error` | The block is already deleted or under a deleted block, or it's a row of a table with merged cells. |
| 403 | `restricted_resource` | **Update content** is off, the database has a task agent attached, the block holds content the integration can't write, or the target is a database the app creates on its own. |
| 404 | `object_not_found` | The block doesn't exist, or the integration can't read it. |

See [Common rules](https://developers.bottari.ai/api-reference/overview.md#errors) for shared errors.

```bash curl theme={null}
curl https://api.bottari.ai/v1/blocks/exampleRow01.exampleBlk01 \
  -X DELETE \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"
```

```json 200 theme={null}
{
  "object": "block",
  "id": "exampleRow01.exampleBlk01",
  "parent": {
    "type": "page_id",
    "page_id": "exampleRow01"
  },
  "created_time": "2026-01-15T02:30:00.000Z",
  "last_edited_time": "2026-01-15T03:10:00.000Z",
  "created_by": {
    "object": "user",
    "id": "22222222-2222-4222-8222-222222222222"
  },
  "last_edited_by": {
    "object": "user",
    "id": "22222222-2222-4222-8222-222222222222"
  },
  "has_children": false,
  "in_trash": true,
  "type": "divider",
  "divider": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Can't edit block that is archived. You must unarchive the block before editing.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.