Heading 2 in the Notion UI:
Keys
Fields marked with an * are available to integrations with any capabilities. Other properties require read content capabilities in order to be returned from the Notion API. Consult the integration capabilities reference for details.
| Field | Type | Description | Example value |
|---|---|---|---|
object* | string | Always "block". | "block" |
id* | string (UUIDv4) | Identifier for the block. | "7af38973-3787-41b3-bd75-0ed3a1edfac9" |
parent | object | Information about the block’s parent. See Parent object. | { "type": "block_id", "block_id": "7d50a184-5bbe-4d90-8f29-6bec57ed817b" } |
type | string (enum) | Type of block. Possible values are: - "bookmark" - "breadcrumb" - "bulleted_list_item" - "callout" - "child_database" - "child_page" - "column" - "column_list" - "divider" - "embed" - "equation" - "file" - "heading_1" - "heading_2" - "heading_3" - "image" - "link_preview" - "numbered_list_item" - "paragraph" - "pdf" - "quote" - "synced_block" - "table" - "table_of_contents" - "table_row" - "template" - "to_do" - "toggle" - "unsupported" - "video" | "paragraph" |
created_time | string (ISO 8601 date time) | Date and time when this block was created. Formatted as an ISO 8601 date time string. | "2020-03-17T19:10:04.968Z" |
created_by | Partial User | User who created the block. | {"object": "user","id": "45ee8d13-687b-47ce-a5ca-6e2e45548c4b"} |
last_edited_time | string (ISO 8601 date time) | Date and time when this block was last updated. Formatted as an ISO 8601 date time string. | "2020-03-17T19:10:04.968Z" |
last_edited_by | Partial User | User who last edited the block. | {"object": "user","id": "45ee8d13-687b-47ce-a5ca-6e2e45548c4b"} |
archived | boolean | The archived status of the block. | false |
in_trash | boolean | Whether the block has been deleted. | false |
has_children | boolean | Whether or not the block has children blocks nested within it. | true |
{type} | block type object | An object containing type-specific block information. | Refer to the block type object section for examples of each block type. |
Block types that support child blocks
Some block types contain nested blocks. The following block types support child blocks:- Bulleted list item
- Callout
- Child database
- Child page
- Column
- Heading 1, when the
is_toggleableproperty istrue - Heading 2, when the
is_toggleableproperty istrue - Heading 3, when the
is_toggleableproperty istrue - Numbered list item
- Paragraph
- Quote
- Synced block
- Table
- Template
- To do
- Toggle
The API does not support all block types.Only the block type objects listed in the reference below are supported. Any unsupported block types appear in the structure, but contain a
type set to "unsupported".Block type objects
Every block object has a key corresponding to the value oftype. Under the key is an object with type-specific block information.
Many block types support rich text. In cases where it is supported, a
rich_text object will be included in the block type object. All rich_text objects will include a plain_text property, which provides a convenient way for developers to access unformatted text from the Notion block.Audio
Audio block objects contain a file object detailing information about the audio file.Supported audio types
The following file types can be attached with external URLs in the API as well as in the Notion app UI:.mp3.wav.ogg.oga.m4a
file_upload ID.
Supported file upload types
See the file upload reference for a list of supported file extensions and content types when attaching a File Upload to a block. Audio blocks only support file types in the “audio” section of the table.Bookmark
Bookmark block objects contain the following information within thebookmark property:
| Field | Type | Description |
|---|---|---|
caption | array of rich text objects text | The caption for the bookmark. |
url | string | The link for the bookmark. |
Breadcrumb
Breadcrumb block objects do not contain any information within thebreadcrumb property.
Bulleted list item
Bulleted list item block objects contain the following information within thebulleted_list_item property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text in the bulleted_list_item block. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown"- "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
children | array of block objects | The nested child blocks (if any) of the bulleted_list_item block. |
Callout
Callout block objects contain the following information within thecallout property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text in the callout block. |
icon | object | An emoji or file object that represents the callout’s icon. If the callout does not have an icon. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown"- "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
Child database
Child database block objects contain the following information within thechild_database property:
| Field | Type | Description |
|---|---|---|
title | string | The plain text title of the database. |
Creating and updating
child_database blocksTo create or update child_database type blocks, use the Create a database and the Update a database endpoints, specifying the ID of the parent page in the parent body param.Child page
Child page block objects contain the following information within thechild_page property:
| Field | Type | Description |
|---|---|---|
title | string | The plain text title of the page. |
Creating and updating
child_page blocksTo create or update child_page type blocks, use the Create a page and the Update page endpoints, specifying the ID of the parent page in the parent body param.Code
Code block objects contain the following information within thecode property:
| Field | Type | Description |
|---|---|---|
caption | array of Rich text object text objects | The rich text in the caption of the code block. |
rich_text | array of Rich text object text objects | The rich text in the code block. |
language | - "abap" - "arduino" - "bash" - "basic" - "c" - "clojure" - "coffeescript" - "c++" - "c#" - "css" - "dart" - "diff" - "docker" - "elixir" - "elm" - "erlang" - "flow" - "fortran" - "f#" - "gherkin" - "glsl" - "go" - "graphql" - "groovy" - "haskell" - "html" - "java" - "javascript" - "json" - "julia" - "kotlin" - "latex" - "less" - "lisp" - "livescript" - "lua" - "makefile" - "markdown" - "markup" - "matlab" - "mermaid" - "nix" - "objective-c" - "ocaml" - "pascal" - "perl" - "php" - "plain text" - "powershell" - "prolog" - "protobuf" - "python" - "r" - "reason" - "ruby" - "rust" - "sass" - "scala" - "scheme" - "scss" - "shell" - "sql" - "swift" - "typescript" - "vb.net" - "verilog" - "vhdl" - "visual basic" - "webassembly" - "xml" - "yaml" - "java/c/c++/c#" | The language of the code contained in the code block. |
Column list and column
Column lists are parent blocks for columns. They do not contain any information within thecolumn_list property.
columns. They do not require any information within the column property, but a width_ratio number between 0 and 1 can be provided to customize the width of a column relative to others in the same column list. When omitted, the default is to use equal widths for all columns. When provided, width_ratios should add up to 1.
Columns can only be appended to column_lists.
column_list block via Append block children, the column_list must have at least two columns, and each column must have at least one child.
Retrieve the content in a column list
Follow these steps to fetch the content in acolumn_list:
Get the
column_list ID from a query to Retrieve block children for the parent page.Divider
Divider block objects do not contain any information within thedivider property.
Embed
Embed block objects include information about another website displayed within the Notion UI. Theembed property contains the following information:
| Field | Type | Description |
|---|---|---|
url | string | The link to the website that the embed block displays. |
Vimeo video links can be embedded in a Notion page via the public API using the embed block type.For example, the following object can be passed to the Append block children endpoint:For other video sources, see Supported video types.
JSON
Equation
Equation block objects are represented as children of paragraph blocks. They are nested within a rich text object and contain the following information within theequation property:
| Field | Type | Description |
|---|---|---|
expression | string | A KaTeX compatible string. |
File
File block objects contain the following information within thefile property:
| Field | Type | Description |
|---|---|---|
caption | array of rich text objects | The caption of the file block. |
type | One of: - "file" - "external" - "file_upload" | Type of file. This enum value indicates which of the following three objects are populated. |
file | Notion-hosted file object | A file object that details information about the file contained in the block: a temporary download url and expiry_time. After the expiry_time, fetch the block again from the API to get a new url. Only valid as a parameter if copied verbatim from the file field of a recent block API response from Notion. To attach a file, provide a type of file_upload instead. |
external | External file object | An object with a url property, identifying a publicly accessible URL. |
file_upload | File upload object | An object with the id of a FileUpload to attach to the block. After attaching, the API response responds with a type of file, not file_upload, so your integration can access a download url. |
name | string | The name of the file, as shown in the Notion UI. Note that the UI may auto-append .pdf or other extensions.When attaching a file_upload, the name parameter is not required. |
Headings
All heading block objects,heading_1, heading_2, and heading_3, contain the following information within their corresponding objects:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text of the heading. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
is_toggleable | boolean | Whether or not the heading block is a toggle heading or not. If true, then the heading block toggles and can support children. If false, then the heading block is a static heading block. |
Image
Image block objects contain a file object detailing information about the image.Supported external image types
The image must be directly hosted. In other words, theurl cannot point to a service that retrieves the image. The following image types are supported:
.bmp.gif.heic.jpeg.jpg.png.svg.tif.tiff
Supported file upload types
See the file upload reference for a list of supported file extensions and content types when attaching a File Upload to a block. Image blocks only support file types in the “image” section of the table.Link Preview
Link Preview block objects contain the originally pastedurl:
Mention
A mention block object is a child of a rich text object that is nested within a paragraph block object. This block type represents any@ tag in the Notion UI, for a user, date, Notion page, Notion database, or a miniaturized version of a Link Preview.
A mention block object contains the following fields:
| Field | Type | Description |
|---|---|---|
type | "database""date""link_preview""page""user" | A constant string representing the type of the mention. |
"database""date""link_preview""page""user" | object | An object with type-specific information about the mention. |
Numbered list item
Numbered list item block objects contain the following information within thenumbered_list_item property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the numbered_list_item block. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
list_start_index | integer (optional) | The start index of a list, used to represent a list that doesn’t start at 1. Only present on the first item of a list. |
list_format | string (enum) (optional) | The type of list format. Possible values are: "numbers", "letters", and "roman". Only present on the first item of a list. |
children | array of block objects | The nested child blocks (if any) of the numbered_list_item block. |
Paragraph
Paragraph block objects contain the following information within theparagraph property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the paragraph block. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
children | array of block objects | The nested child blocks (if any) of the paragraph block. |
| Property | Type | Description |
|---|---|---|
caption | array of rich text objects | A caption, if provided, for the PDF block. |
type | One of: - "file" - "external" - "file_upload" | A constant string representing the type of PDF. file indicates a Notion-hosted file, and external represents a third-party link. file_upload is only valid when providing parameters to attach a File Upload to a PDF block. |
external |file |file_upload | file object | An object containing type-specific information about the PDF. |
Supported file upload types
See the file upload reference for a list of supported file extensions and content types when attaching a File Upload to a block. PDF blocks only support a type of.pdf.
Quote
Quote block objects contain the following information within thequote property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the quote block. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
children | array of block objects | The nested child blocks, if any, of the quote block. |
Synced block
Similar to the Notion UI, there are two versions of asynced_block object: the original block that was created first and doesn’t yet sync with anything else, and the duplicate block or blocks synced to the original.
An original synced block must be created before corresponding duplicate block or blocks can be made.
Original synced block
Original synced block objects contain the following information within thesynced_block property:
| Field | Type | Description |
|---|---|---|
synced_from | null | The value is always null to signify that this is an original synced block that does not refer to another block. |
children | array of block objects | The nested child blocks, if any, of the synced_block block. These blocks will be mirrored in the duplicate synced_block. |
Duplicate synced block
Duplicate synced block objects contain the following information within thesynced_from object:
| Field | Type | Description |
|---|---|---|
type | string (enum) | The type of the synced from object. Possible values are: - "block_id" |
block_id | string (UUIDv4) | An identifier for the original synced_block. |
Table
Table block objects are parent blocks for table row children. Table block objects contain the following fields within thetable property:
| Field | Type | Description |
|---|---|---|
table_width | integer | The number of columns in the table. Note that this cannot be changed via the public API once a table is created. |
has_column_header | boolean | Whether the table has a column header. If true, then the first row in the table appears visually distinct from the other rows. |
has_row_header | boolean | Whether the table has a header row. If true, then the first column in the table appears visually distinct from the other columns. |
Table rows
Follow these steps to fetch thetable_rows of a table:
Get the
table ID from a query to Retrieve block children for the parent page.table_row block object contains the following fields within the table_row property:
| Property | Type | Description |
|---|---|---|
cells | array of array of rich text objects | An array of cell contents in horizontal display order. Each cell is an array of rich text objects. |
When creating a table block via the Append block children endpoint, the
table must have at least one table_row whose cells array has the same length as the table_width.Table of contents
Table of contents block objects contain the following information within thetable_of_contents property:
| Property | Type | Description |
|---|---|---|
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
Template
Deprecation NoticeAs of March 27, 2023 creation of template blocks will no longer be supported.
template property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the title of the template. |
children | array of block objects | The nested child blocks, if any, of the template block. These blocks are duplicated when the template block is used in the UI. |
To do
To do block objects contain the following information within theto_do property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the To do block. |
checked | boolean (optional) | Whether the To do is checked. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
children | array of block objects | The nested child blocks, if any, of the To do block. |
Toggle blocks
Toggle block objects contain the following information within thetoggle property:
| Field | Type | Description |
|---|---|---|
rich_text | array of rich text objects | The rich text displayed in the Toggle block. |
color | string (enum) | The color of the block. Possible values are: - "blue" - "blue_background" - "brown" - "brown_background" - "default" - "gray" - "gray_background" - "green" - "green_background" - "orange" - "orange_background" - "yellow" - "green" - "pink" - "pink_background" - "purple" - "purple_background" - "red" - "red_background" - "yellow_background" |
children | array of block objects | The nested child blocks, if any, of the Toggle block. |
Video
Video block objects contain a file object detailing information about the video.Supported video types
.amv.asf.avi.f4v.flv.gifv.mkv.mov.mpg.mpeg.mpv.mp4.m4v.qt.wmv- YouTube video links that include
embedorwatch. E.g.https://www.youtube.com/watch?v=[id],https://www.youtube.com/embed/[id]
Vimeo video links are not currently supported by the video block type. However, they can be embedded in Notion pages using the
embed block type. See Embed for more information.