Update Block

PATCH /blocks/:block_id

Path Parameters

Parameter	Type	Required	Description
`block_id`	UUID	Yes	The unique identifier of the block to update

Request Body

{
  "type": "string",
  "paragraph": { ... }
}

Core Fields

Field	Type	Required	Description
`type`	string	Yes	The type of block. Must match the block's current type or be a valid type change. Determines which block-specific field should be provided.

Block Types

Supported Types

Type	JSON Key	Description
`divider`	`divider`	Horizontal line separator
`heading_1`	`heading_1`	Top-level heading
`heading_2`	`heading_2`	Second-level heading
`heading_3`	`heading_3`	Third-level heading
`paragraph`	`paragraph`	Text paragraph
`table`	`table`	Table container
`table_row`	`table_row`	Row within a table
`image`	`image`	Image block
`equation`	`equation`	Mathematical equation
`bulleted_list_item`	`bulleted_list_item`	Bulleted list item
`numbered_list_item`	`numbered_list_item`	Numbered list item
`callout`	`callout`	Highlighted callout box

Block Type Specific Fields

Divider

Simple horizontal separator with no additional properties.

{
  "type": "divider",
  "divider": {}
}

Heading (heading_1, heading_2, heading_3)

{
  "type": "heading_1",
  "heading_1": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Updated Heading Text",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated Heading Text",
        "href": null
      }
    ],
    "is_toggleable": false,
    "color": "default"
  }
}

Field	Type	Description
`rich_text`	array	Array of rich text objects containing the heading content
`is_toggleable`	boolean	Whether the heading can be collapsed/expanded
`color`	string	Color of the heading text (defaults to "default")

Paragraph

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Updated paragraph content with ",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated paragraph content with ",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": "formatted text",
          "link": null
        },
        "annotations": {
          "bold": true,
          "italic": true,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "formatted text",
        "href": null
      }
    ],
    "color": "default"
  }
}

Field	Type	Description
`rich_text`	array	Array of rich text objects
`color`	string	Text color (defaults to "default")

Table

{
  "type": "table",
  "table": {
    "table_width": 4,
    "has_column_header": true,
    "has_row_header": true
  }
}

Field	Type	Description
`table_width`	integer	Number of columns in the table
`has_column_header`	boolean	Whether the first row is a header
`has_row_header`	boolean	Whether the first column is a header

Table Row

{
  "type": "table_row",
  "table_row": {
    "cells": [
      [
        {
          "type": "text",
          "text": { "content": "Updated Cell 1", "link": null },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Updated Cell 1",
          "href": null
        }
      ],
      [
        {
          "type": "text",
          "text": { "content": "Updated Cell 2", "link": null },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Updated Cell 2",
          "href": null
        }
      ]
    ]
  }
}

Field	Type	Description
`cells`	array[][]	2D array where each inner array is a cell containing rich text objects

Image

External Image:

{
  "type": "image",
  "image": {
    "type": "external",
    "external": {
      "id": null,
      "url": "https://example.com/new-image.jpg"
    },
    "caption": [
      {
        "type": "text",
        "text": { "content": "Updated caption", "link": null },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated caption",
        "href": null
      }
    ]
  }
}

File-based Image:

{
  "type": "image",
  "image": {
    "type": "file",
    "file": {
      "id": "new-file-uuid-here",
      "url": null,
      "expiry_time": null
    },
    "caption": []
  }
}

Field	Type	Description
`type`	string	"external" or "file"
`external`	object	External URL reference (when type is "external")
`file`	object	Internal file reference (when type is "file")
`caption`	array	Array of rich text for image caption

Equation

{
  "type": "equation",
  "equation": {
    "expression": "\\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}"
  }
}

Field	Type	Description
`expression`	string	LaTeX or mathematical expression

Bulleted List Item

{
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [
      {
        "type": "text",
        "text": { "content": "Updated bullet point", "link": null },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated bullet point",
        "href": null
      }
    ],
    "color": "default"
  }
}

Field	Type	Description
`rich_text`	array	Array of rich text objects
`color`	string	Text color (defaults to "default")

Numbered List Item

{
  "type": "numbered_list_item",
  "numbered_list_item": {
    "rich_text": [
      {
        "type": "text",
        "text": { "content": "Updated numbered item", "link": null },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated numbered item",
        "href": null
      }
    ],
    "color": "default"
  }
}

Field	Type	Description
`rich_text`	array	Array of rich text objects
`color`	string	Text color (defaults to "default")

Callout

{
  "type": "callout",
  "callout": {
    "rich_text": [
      {
        "type": "text",
        "text": { "content": "Updated important notice!", "link": null },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Updated important notice!",
        "href": null
      }
    ],
    "icon": "info",
    "color": "blue_background"
  }
}

Field	Type	Description
`rich_text`	array	Array of rich text objects
`icon`	string	Emoji or icon identifier to display
`color`	string	Background or text color

Rich Text Object Structure

Rich text objects allow for formatted text with various annotations.

{
  "type": "text",
  "text": {
    "content": "The actual text content",
    "link": "https://optional-link.com"
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "The actual text content",
  "href": null
}

Rich Text Types

Type	Description	Example
`text`	Plain or formatted text	Regular content
`equation`	Inline mathematical equation	$x^2$
`mention`	Reference to user or page	@user or @page

Annotations

Property	Type	Description
`bold`	boolean	Bold text
`italic`	boolean	Italic text
`strikethrough`	boolean	Strikethrough text
`underline`	boolean	Underlined text
`code`	boolean	Monospace code formatting
`color`	string	Text or background color

Complete Request Examples

Example 1: Update paragraph text

Scenario: Modify the content of an existing paragraph block.

PATCH /blocks/para-uuid-123

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "This is the updated content for the paragraph.",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "This is the updated content for the paragraph.",
        "href": null
      }
    ],
    "color": "default"
  }
}

Example 2: Update heading with formatting

Scenario: Change heading text and add formatting.

PATCH /blocks/heading-uuid-456

{
  "type": "heading_2",
  "heading_2": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Section 2: ",
          "link": null
        },
        "annotations": {
          "bold": true,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Section 2: ",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": "Methodology",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": true,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Methodology",
        "href": null
      }
    ],
    "is_toggleable": true,
    "color": "blue"
  }
}

Example 3: Update table row cells

Scenario: Modify cell contents in a table row.

PATCH /blocks/row-uuid-789

{
  "type": "table_row",
  "table_row": {
    "cells": [
      [
        {
          "type": "text",
          "text": { "content": "Temperature", "link": null },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Temperature",
          "href": null
        }
      ],
      [
        {
          "type": "text",
          "text": { "content": "25.5", "link": null },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "25.5",
          "href": null
        }
      ],
      [
        {
          "type": "text",
          "text": { "content": "°C", "link": null },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "°C",
          "href": null
        }
      ]
    ]
  }
}

Example 4: Update callout with new icon and color

Scenario: Change a warning callout to an info callout.

PATCH /blocks/callout-uuid-abc

{
  "type": "callout",
  "callout": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Note: This section has been reviewed and approved.",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "Note: This section has been reviewed and approved.",
        "href": null
      }
    ],
    "icon": "check",
    "color": "green_background"
  }
}

Response

Success Response

Status Code: 200 OK

{
  "request_id": "req-uuid-here",
  "data": {
    "id": "block-uuid",
    "object": "block",
    "parent_id": "parent-block-uuid",
    "has_children": false,
    "archived": false,
    "in_trash": false,
    "type": "paragraph",
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Updated content",
            "link": null
          },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Updated content",
          "href": null
        }
      ],
      "color": "default"
    },
    "document_id": "document-uuid",
    "chapter_id": "chapter-uuid",
    "created_at": "2024-01-15T10:30:00Z",
    "created_by": "user-uuid",
    "updated_at": "2024-01-15T11:45:00Z",
    "updated_by": "user-uuid"
  }
}

Error Responses

400 Bad Request

Validation error or malformed request.

{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "message": "type is required"
    }
  ]
}

401 Unauthorized

Missing or invalid authentication token.

{
  "code": 401,
  "message": "Unauthorized",
  "errors": [
    {
      "message": "Invalid or expired token"
    }
  ]
}

404 Not Found

Block not found.

{
  "code": 404,
  "message": "Not Found",
  "errors": [
    {
      "message": "Block not found"
    }
  ]
}

500 Internal Server Error

Server-side error.

{
  "code": 500,
  "message": "Internal Server Error",
  "errors": [
    {
      "message": "An unexpected error occurred"
    }
  ]
}

Best Practices

Match type with field: Ensure the type field matches the corresponding block-specific object (e.g., type: "paragraph" must have paragraph field).
Provide complete block data: When updating, provide the entire block-specific object, not just the changed fields. The system replaces the entire block content.
Rich text consistency: Always include all required fields in rich text objects, even if using default values.
Color defaults: If color is not specified for blocks that support it, the system defaults to "default".
Preserve formatting: When updating text content, ensure annotations are preserved unless intentionally changing them.
Table row cell count: When updating table rows, ensure the number of cells matches the parent table's table_width.
Validate before update: Consider retrieving the current block state before updating to ensure you're not overwriting concurrent changes.
Audit trail: All updates are tracked with timestamps and user information in the audit log.

Update Block

/blocks/:block_id

Path Parameters​

Request Body​

Core Fields​

Block Types​

Supported Types​

Block Type Specific Fields​

Divider​

Heading (heading_1, heading_2, heading_3)​

Paragraph​

Table​

Table Row​

Image​

Equation​

Bulleted List Item​

Numbered List Item​

Callout​

Rich Text Object Structure​

Rich Text Types​

Annotations​

Complete Request Examples​

Example 1: Update paragraph text​

Example 2: Update heading with formatting​

Example 3: Update table row cells​

Example 4: Update callout with new icon and color​

Response​

Success Response​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

500 Internal Server Error​

Best Practices​

Request​

Responses​