Block Types

Review all readable block types and the subset of block types supported for writes.

The read APIs can return every block type supported by the service. Write APIs accept a defined subset of block types.

Readable Block Types

Group	Types
Text and structure	`paragraph`, `heading_1`, `heading_2`, `heading_3`, `bulleted_list_item`, `numbered_list_item`, `to_do`, `quote`, `code`, `callout`, `divider`, `toggle`, `equation`
Media and embeds	`bookmark`, `embed`, `image`, `file`
Data and layout	`table`, `table_row`, `column_list`, `column`
Page and containers	`link_to_page`, `link_page`, `child_page`, `child_database`, `child_mind_map`, `mind_map`, `folder`, `template`, `synced_block`

A block content object is stored under the field named by type.
Write requests must use writable block types only.
Some block types can contain children; each children array can contain at most 100 blocks.
A column_list must contain 2–100 direct column children. column.width_ratio must be positive and defaults to 1.
child_database creates a database page by default. Set is_inline to true for an inline database. A title property and default table view are created automatically when needed.
child_mind_map creates a mind map page and mind_map creates an inline mind map. Supply the initial tree through nodes; edit nodes later through /v2/mind-maps/{mind_map_id}.
Folder descendants can contain only file and folder blocks.
link_page input is accepted for legacy compatibility and is normalized to link_to_page after a write.
template and synced_block remain read-only.
Unsupported block types return 400 unsupported_block_type.
Use the Markdown endpoint when a full-page text export is a better fit than block-level reads.