Developer API

Block Types

V2

Block Types

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

Block Types

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`, `callout`, `divider`, `table_of_contents`
Media and embeds	`bookmark`, `embed`, `image`, `file`, `video`, `audio`, `pdf`
Data and layout	`table`, `table_row`, `column_list`, `column`, `breadcrumb`
Advanced	`toggle`, `equation`, `link_to_page`, `synced_block`, `template`, `unsupported`

Writable Block Types

Type	Writable content field
`paragraph`	`paragraph`
`heading_1`	`heading_1`
`heading_2`	`heading_2`
`heading_3`	`heading_3`
`bulleted_list_item`	`bulleted_list_item`
`numbered_list_item`	`numbered_list_item`
`to_do`	`to_do`
`quote`	`quote`
`code`	`code`
`callout`	`callout`
`divider`	No content object required.
`bookmark`	`bookmark`
`embed`	`embed`
`image`	`image`
`file`	`file`
`table`	`table`
`table_row`	`table_row`
`toggle`	`toggle`
`equation`	`equation`
`link_to_page`	`link_to_page`

Rules

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; nested writes are limited by the API depth constraints.
Unsupported block types return 400 unsupported_block_type.
Use Markdown endpoints when a full-page text replacement is a better fit than block-level writes.

References