Update a block

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
    }
  }'

{
  "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"
}

{
  "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"
}

PATCH

blocks

{id}

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
    }
  }'

{
  "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"
}

{
  "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"
}

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. Sending a document ID here returns 400.

string

required

Bearer <token>. See Tokens.

string

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

string

required

The block ID.

object

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

boolean

true deletes the block, like Delete a block. 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. 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 also keep it when the commented text doesn’t change.

Response

The updated block object. See Retrieve a block.

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 for shared errors.

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
    }
  }'

{
  "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"
}

{
  "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"
}

Common

Users

Search

Databases and data sources

Pages

Blocks

Async tasks

Comments

What can change

Rules

Comments

Response

Errors

​What can change

​Rules

​Comments

​Response

​Errors

What can change

Rules

Comments

Response

Errors