Update Block

Use Case

Use this endpoint to partially update one block. Send the type-specific field that matches the block type, plus shared fields such as trash state when supported.

Endpoint

Permissions

Requires blocks.write and write access to the block.

Parameters

Request Example

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Updated project kickoff notes"
        }
      }
    ],
    "color": "default"
  }
}

Response Example

{
  "object": "block",
  "id": "44444444-4444-4444-8444-444444444444",
  "parent": {
    "type": "page_id",
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "created_time": "2026-04-09T08:00:00.000Z",
  "last_edited_time": "2026-04-09T09:30:00.000Z",
  "created_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "last_edited_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "has_children": false,
  "in_trash": false,
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Project kickoff notes",
          "link": null
        },
        "plain_text": "Project kickoff notes",
        "href": null
      }
    ],
    "color": "default"
  }
}

Behavior

• Only the submitted fields are changed.
• The type-specific content field must match the block type.
• Unsupported writable block types return unsupported_block_type.
• Use the append children endpoint to add child blocks; this endpoint does not append descendants.

Errors

• 400 validation_error: invalid update shape.
• 400 unsupported_block_type: block type cannot be updated through this endpoint.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing blocks.write or no access.
• 404 not_found: block does not exist.

Related Docs

Prerequisites

• Get Block

Next Steps

• Get Block Children

References

• Block Types
• Error Codes