> ## 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.

# Update a block

> Change a block's content or settings, or restore a deleted block. Requires Update content.

Changes one block, or moves it to or from the trash. Requires **Update content**. Only the fields you send change, but headings and list items always need `rich_text`. An empty body changes nothing and returns 200.

To change a document's or subpage's title, use [Update a page](https://developers.bottari.ai/api-reference/pages/update.md). Sending a document ID here returns 400.

**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*

The block ID.

**\<block type>** `object`

The key is the block's current type, and the value holds the fields to change. See the table below.

**in\_trash** `boolean`

`true` deletes the block, like [Delete a block](https://developers.bottari.ai/api-reference/blocks/delete.md). `false` restores it. Sending this with the type key saves both.

## What can change

| Block | Fields |
| - | - |
| `quote`, `toggle` | `rich_text`, `color` |
| `bulleted_list_item`, `numbered_list_item` | `rich_text` (required), `color` |
| `paragraph` | `rich_text`, `color`. `icon` only for a tab's paragraph. |
| Headings | `rich_text` (required), `color`, `is_toggleable` |
| `to_do` | `rich_text`, `color`, `checked` |
| `callout` | `rich_text`, `color`, `icon` |
| `code` | `rich_text`, `language`, `caption` |
| `equation` | `expression` |
| `bookmark`, `embed` | `url` |
| `image` | `external.url`, `caption` |
| Uploaded `image`, `video`, `audio`, `pdf`, `file` | `caption`. The file can't change. |
| `link_to_page` | `page_id` or `database_id`. The target must be readable. |
| `table` | `has_column_header`, `has_row_header` |
| `table_row` | `cells` |
| `column` | `width_ratio` |

## Rules

* A block's type can't change. The response is 400 `Block type mismatch: ...`
* `table_of_contents.color` and `caption` on `bookmark` and `embed` are accepted and ignored.
* `table_width` can't change, and `synced_from` can't change. Sending the current `synced_from` does nothing.
* A top-level `children` key returns 400. To add children, use [Append block children](https://developers.bottari.ai/api-reference/blocks/append.md). `children` inside the type key is ignored.
* A heading with children can't turn off `is_toggleable`. The response is 400 `Cannot remove toggle from ... You must remove its children first.`
* A row of a table with merged cells can't be updated. The response is 400.
* Writing a cell replaces it with one paragraph of text, so an image or extra paragraphs in that cell are removed. Sending back what you read keeps them.
* To stop mentions from notifying people, use `notifications` when appending. This endpoint doesn't accept it and always notifies.

## Comments

Replacing text removes the anchor of any inline comment on it. The comment moves to the document, with `original_content_deleted: true`. Read it with the document ID, not the block ID. Sending back the same `rich_text` you read keeps the anchor. [Markdown updates](https://developers.bottari.ai/api-reference/pages/update-markdown.md) also keep it when the commented text doesn't change.

## Response

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

## Errors

| Status | `code` | Cause |
| - | - | - |
| 400 | `validation_error` | A value is wrong, the type doesn't match, or the target is a document. A deleted block returns `Can't edit block that is archived. You must unarchive the block before editing.` A block under a deleted block returns `Can't edit page on block with an archived ancestor. You must unarchive the ancestor before editing page.` |
| 403 | `restricted_resource` | **Update content** is off, or the database has a task agent attached. |
| 404 | `object_not_found` | The block doesn't exist, or the integration can't read it. A person the integration can't see, in a mention, also returns this. |

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 PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "to_do": {
      "checked": true
    }
  }'
```

```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": false,
  "type": "to_do",
  "to_do": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Update the changelog",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Update the changelog",
        "href": null
      }
    ],
    "checked": true,
    "color": "default"
  },
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```

```json 400 theme={null}
{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Block type mismatch: this block is a `paragraph`, but your request includes fields for a `heading_1` block. Changing a block's type is not supported.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}
```


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