update_block
Edit a single block in Notion without losing its deep-link anchors or comments. Use for targeted updates like fixing headings or toggling checkboxes while preserving block identity.
Instructions
Update a single block in place by ID. Preserves the block's identity (deep-link anchors and inline-comment threads attached to the block survive the edit). Use this for surgical edits: fixing a heading, toggling a checkbox, rewriting one paragraph. For multi-block edits, use append_content, replace_content, or update_section.
Type lock-in: the markdown must parse to the same block type as the existing block. update_block cannot change a block's type — Notion's API forbids it. To change a block's type, use replace_content or delete + append.
Updatable types: paragraph, heading_1, heading_2, heading_3, toggle, bulleted_list_item, numbered_list_item, quote, callout, to_do, code, equation. Container blocks (toggle, callout) update first-level content only — children stay untouched. Non-updatable types (divider, table, image, bookmark, etc.) accept only archived: true to delete the block.
To delete a block, pass archived: true instead of markdown. Exactly one of markdown or archived is required.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | Block ID to update | |
| markdown | No | New content for the block. Must parse to a single block of the same type as the existing block. For to_do blocks, `- [x]` / `- [ ]` syntax sets the checked state. | |
| checked | No | to_do only: explicit check-state override (otherwise inferred from `- [x]` / `- [ ]`). | |
| archived | No | Set true to delete the block (sends in_trash: true). | |
| dry_run | No | Preview validation and planned effect without mutating Notion. Default false. |