A block object represents content within Notion. Blocks can be text, lists, media, and more. A page is a type of block, too!
{
"object": "block",
"id": "9bc30ad4-9373-46a5-84ab-0a7845ee52e6",
"created_time": "2021-03-16T16:31:00.000Z",
"created_by": {
"object": "user",
"id": "cb38e95d-00cf-4e7e-adce-974f4a44a547"
},
"last_edited_time": "2021-03-16T16:32:00.000Z",
"last_edited_by": {
"object": "user",
"id": "e79a0b74-3aba-4149-9f74-0bb5791a6ee6"
},
"has_children": false,
"type": "to_do",
"archived": false,
"to_do": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "Lacinato kale",
"href": null
}
],
"checked": false,
"color": "default",
}
}
Some blocks have more content nested inside them. Some examples are indented paragraphs, lists, and toggles. The nested content is called children
, and children are blocks, too!
Block types which support children are "paragraph"
, "bulleted_list_item"
, "numbered_list_item"
, "toggle"
, "to_do"
, "quote"
, "callout"
, "synced_block"
, "template"
, "column"
, "child_page"
, "child_database"
, and "table"
.
Some block types aren't available yet
At present the API only supports the block types which are listed in the reference below. Any unsupported block types will continue to appear in the structure, but only contain a
type
set to"unsupported"
.
Block object keys
Each block object contains the following keys. In addition, it must contain a key corresponding with the value of type
. The value is an object containing a type-specific block information. The type-specific block information is described in the sections below.
Properties 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.
For more information on integration capabilities, see the capabilities guide.
Property | Type | Description | Example value |
---|---|---|---|
|
| Always |
|
|
| Identifier for the block. |
|
|
| Type of block. Possible values include |
|
|
| Date and time when this block was created. Formatted as an ISO 8601 date time string. |
|
| User who created the block. |
| |
|
| Date and time when this block was last updated. Formatted as an ISO 8601 date time string. |
|
| User who last edited the block. |
| |
|
| The archived status of the block. |
|
|
| Whether or not the block has children blocks nested within it. |
|
|
| An object containing a type-specific block information | (see sidebar) |
Block Type Object
Every block object has a key corresponding to the value of type
. Under the key is an object with type-specific block information.
Paragraph blocks
Paragraph block objects contain the following information within the paragraph
property:
{
"type": "paragraph",
//...other keys excluded
"paragraph": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the paragraph block. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the paragraph block. |
Heading one blocks
Heading one block objects contain the following information within the heading_1
property:
{
"type": "heading_1",
//...other keys excluded
"heading_1": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default"
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the heading block. |
|
| Color of the block. Possible values are: |
Heading two blocks
Heading two block objects contain the following information within the heading_2
property:
{
"type": "heading_2",
//...other keys excluded
"heading_2": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default"
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the heading block. |
|
| Color of the block. Possible values are: |
Heading three blocks
Heading three block objects contain the following information within the heading_3
property:
{
"type": "heading_3",
//...other keys excluded
"heading_3": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default"
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the heading block. |
|
| Color of the block. Possible values are: |
Callout blocks
Callout block objects contain the following information within the callout
property:
{
"type": "callout",
// ..other keys excluded
"callout": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
},
}],
"icon": {
"emoji": "⭐"
},
"color": "default"
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the heading block. |
| Page icon. | |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the callout block. |
Quote blocks
Quote block objects contain the following information within the quote
property
{
"type": "quote",
// ..other keys excluded
"quote": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
},
}],
"color": "default"
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the quote block. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the quote block. |
Bulleted list item blocks
Bulleted list item block objects contain the following information within the bulleted_list_item
property:
{
"type": "bulleted_list_item",
//...other keys excluded
"bulleted_list_item": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the bulleted_list_item block. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the bulleted_list_item block. |
Numbered list item blocks
Numbered list item block objects contain the following information within the numbered_list_item
property:
{
"type": "numbered_list_item",
//...other keys excluded
"numbered_list_item": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the numbered_list_item block. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the numbered_list_item block. |
To do blocks
To do block objects contain the following information within the to_do
property:
{
"type": "to_do",
//...other keys excluded
"to_do": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"checked": false,
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the to_do block. |
|
| Whether the to_do is checked or not. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the to_do block. |
Toggle blocks
Toggle block objects contain the following information within the toggle
property:
{
"type": "toggle",
//...other keys excluded
"toggle": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
Property | Type | Description |
---|---|---|
| array of rich text objects | Rich text in the toggle block. |
|
| Color of the block. Possible values are: |
| array of block objects | Any nested children blocks of the toggle block. |
Code blocks
Code block objects contain the following information within the code
property:
{
"type": "code",
//...other keys excluded
"code": {
"rich_text": [{
"type": "text",
"text": {
"content": "const a = 3"
}
}],
"language": "javascript"
}
}
Property | Type | Description |
---|---|---|
| array of Rich text object text objects | Rich text in code block |
| array of Rich text object text objects | Rich text in caption of the code block |
|
| Coding language in code block |
Child page blocks
Child page block objects contain the following information within the child_page
property:
{
"type": "child_page",
//...other keys excluded
"child_page": {
"title": "Lacinato kale"
}
}
Creating and Updating child_pages
To create or update
child_page
type blocks, use the Create Page and the Update page endpoint.
Property | Type | Description |
---|---|---|
| string | Plain text of page title. |
Child database blocks
Child database block objects contain the following information within the child_database
property:
{
"type": "child_database",
//...other keys excluded
"child_database": {
"title": "My database"
}
}
Creating and Updating child_databases
To create or update
child_database
type blocks, use the Create database and the Update database endpoint.
Property | Type | Description |
---|---|---|
| string | Plain text of the database title |
Embed blocks
Embed blocks include block types that allow displaying another website within Notion.
Differences in embed blocks between the Notion app and the API
The Notion app uses a 3rd-party service, Embedly, to validate and request metadata for embeds given a URL. This works well in a web app because Notion can kick off an asynchronous request for URL information, which might take seconds or longer to complete, and then update the block with the metadata in the UI after receiving a response from Embedly.
We chose not to call Embedly when creating embed blocks in the API because the API needs to be able to return faster than the UI, and because the response from Embedly could actually cause us change the block type. This would result in a slow and potentially confusing experience as the block in the response would not match the block sent in the request.
The result is that embed blocks created via the API may not look exactly like their counterparts created in the Notion app.
These block types are:
- Framer
- Twitter (tweets)
- Google Drive documents
- Gist
- Figma
- Invision,
- Loom
- Typeform
- Codepen
- PDFs
- Google Maps
- Whimisical
- Miro
- Abstract
- excalidraw
- Sketch
- Replit
There is no need to specify the specific embed type, only the URL.
Embed block objects contain the following information within the embed
property:
{
"type": "embed",
//...other keys excluded
"embed": {
"url": "https://website.domain"
}
}
Property | Type | Description |
---|---|---|
| string | Link to website the embed block will display. |
Image blocks
Includes supported image urls (i.e. ending in .png
, .jpg
, .jpeg
, .gif
, .tif
, .tiff
, .bmp
, .svg
, or .heic
)
{
"type": "image",
//...other keys excluded
"image": {
"type": "external",
"external": {
"url": "https://website.domain/images/image.png"
}
}
}
Property | Type | Description |
---|---|---|
| Image file reference |
Video blocks
Includes supported video urls (e.g. ending in .mkv
, .flv
, .gifv
, .avi
, .mov
, .qt
, .wmv
, .asf
, .amv
, .mp4
, .m4v
, .mpeg
, .mpv
, .mpg
, .f4v
, etc.)
{
"type": "video",
//...other keys excluded
"video": {
"type": "external",
"external": {
"url": "https://website.domain/files/video.mp4"
}
}
}
Property | Type | Description |
---|---|---|
| Video file reference |
File blocks
{
"type": "file",
//...other keys excluded
"file": {
"type": "external",
"external": {
"url": "https://website.domain/files/doc.txt"
}
}
}
Property | Type | Description |
---|---|---|
| File reference | |
| array of Rich text object text objects | Caption of the file block |
PDF blocks
{
"type": "pdf",
//...other keys excluded
"pdf": {
"type": "external",
"external": {
"url": "https://website.domain/files/doc.pdf"
}
}
}
Property | Type | Description |
---|---|---|
| PDF file reference |
Bookmark blocks
{
"type": "bookmark",
//...other keys excluded
"bookmark": {
"url": "https://website.domain"
}
}
Bookmark block objects contain the following information within the bookmark
property:
Property | Type | Description |
---|---|---|
| string | Bookmark link |
| array of Rich text object text objects | Caption of the bookmark block |
Equation blocks
{
"type": "equation",
//...other keys excluded
"equation": {
"expression": "e=mc^2"
}
}
Equation block objects contain the following information within the equation
property
Property | Type | Description |
---|---|---|
| string | A KaTeX compatible string |
Divider blocks
{
"type": "divider",
//...other keys excluded
"divider": {}
}
Divider block objects do not contain any information within the divider
property
Table of contents blocks
{
"type": "table_of_contents",
//...other keys excluded
"table_of_contents": {
"color": "default"
}
}
Table of contents block objects contain the following information within the table_of_contents
property
Property | Type | Description |
---|---|---|
|
| Color of the block. Possible values are: |
Breadcrumb blocks
{
"type": "breadcrumb",
//...other keys excluded
"breadcrumb": {}
}
Breadcrumb block objects do not contain any information within the breadcrumb
property
Column List and Column Blocks
Column Lists are parent blocks for column children. They do not contain any information within the column_list
property and can only contain children of type column
.
Columns are parent blocks for any supported block children, excluding column
s. They do not contain any information within the column
property. They can only be appended to column_list
s.
When creating a column list block via Append block children, the column_list
must have at least 2 column
s, and those column
s must have at least one child each.
When fetching content for a column_list
, first fetch the the column
children via Retrieve block children. Then fetch the children for each column
block.
{
"type": "column_list",
//...other keys excluded
"column_list": {}
}
Column List blocks contain the following information in the column_list
property:
Property | Type | Description |
---|---|---|
| array of | List of columns in the |
{
"type": "column",
//...other keys excluded
"column": {}
}
Column blocks contain the following information in the column
property.
Property | Type | Description |
---|---|---|
| array of block objects | List of blocks in a single column. |
Link Preview blocks
{
"type": "link_preview",
//...other keys excluded
"link_preview": {
"url": "https://github.com/example/example-repo/pull/1234"
}
}
Link Preview block objects return the originally pasted url
. NOTE: The link_preview
block will only be returned as part of a response. It cannot be created via the API.
Template blocks
{
"type": "template",
"template": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Create callout template"
}
}
],
"children": [
{
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Placeholder callout text"
}
}
]
}
}
]
}
}
Template block objects contain the following information within the template
property:
Property | Type | Description |
---|---|---|
| array of rich text objects | rich text in the title of the template |
| array of block objects | Any nested children blocks of the template block. These blocks will be duplicated when the template block is used in the UI. |
Link to page blocks
{
"type": "link_to_page",
"link_to_page": {
"type": "page_id",
"page_id": "{mock_page_id}"
}
}
Link to page objects contain a key corresponding with the value of type
. The value is a type-specific string as described below.
Property | Type | Description | Example value |
---|---|---|---|
|
| Type of this link to page object. Possible values are: |
|
|
| Identifier for a page |
|
|
| Identifier for a database page |
|
Synced Block blocks
Similar to the UI, there are two versions of a synced_block
-- the original block that was created first and doesn't yet sync with anything else, and the reference blocks that are synced to the original synced block.
Original Synced Block
To create a synced_block
, the developer needs to create an original synced block. Developers will be able to identify the original synced_block
because it does not "sync_from" any other block (synced_from
property is set to null
).
This is an example of an "original" synced_block
. Note that all of the blocks available to be synced in another synced_block
are captured in the children
property.
{
"type": "synced_block",
"synced_block": {
"synced_from": null,
"children": [
{
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Callout in synced block"
}
}
]
}
}
]
}
}
"Original" synced block objects contain the following information within the synced_block
property:
Property | Type | Description |
---|---|---|
|
| Value is always |
| array of block objects | Any nested children blocks of the |
Reference Synced Blocks
To sync the content of the original synced_block
with another synced_block
, the developer simply needs to refer to that synced_block
using the synced_from
property.
Below is an example of a synced_block
referring to another synced_block
. Note that only "original" synced blocks can be referenced in the synced_from
property.
{
"type": "synced_block",
"synced_block": {
"synced_from": {
"block_id": "original_synced_block_id"
}
}
}
"References" synced block objects contain the following information within the synced_block
property:
Property | Type | Description |
---|---|---|
| Synced From Object | Object that contains the id of the original synced_block |
Synced From Object
Synced From objects contain a key corresponding with the value of type
. The value is a type-specific string as described below.
Property | Type | Description | Example value |
---|---|---|---|
|
| Type of this synced from object. Possible values are: |
|
|
| Identifier of an original synced_block |
|
Table blocks
Tables are parent blocks for table row children. They can only contain children of type table_row
.
When creating a table block via the Append block children endpoint, the table
must have at least 1 table_row
whose cells
array has the same length as the table_width
.
{
"type": "table",
"table": {
"table_width": 1,
"has_column_header": false,
"has_row_header": false,
"children": [
{
"type": "table_row",
"table_row": {
"cells": [
[
{
"type": "text",
"text": {
"content": "column 1 content"
},
"plain_text": "column 1 content"
}
]
]
}
}
]
}
}
To fetch content for a table
, fetch the the table_row
children via Retrieve block children. The table
block itself only contains formatting data, no content.
{
"type": "table",
"table": {
"table_width": 3,
"has_column_header": false,
"has_row_header": false,
}
}
Table blocks contain the following within the table
property:
Property | Type | Description | Example value |
---|---|---|---|
|
| Number of columns in the table. Note that this cannot be changed via the public API once a table is created. | 3 |
|
| Whether or not the table has a column header. If |
|
|
| Whether or not the table has a header row. If |
|
| array of | List of | [ |
The number of columns in a table can only be set when the table is first created
Note that the number of columns in a table can only be set when the table is first created, not via subsequent calls to the update block endpoint.
Table row blocks
{
"type": "table_row",
"table_row": {
"cells": [
[
{
"type": "text",
"text": {
"content": "column 1 content",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "column 1 content",
"href": null
}
],
[
{
"type": "text",
"text": {
"content": "column 2 content",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "column 2 content",
"href": null
}
],
[
{
"type": "text",
"text": {
"content": "column 3 content",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "column 3 content",
"href": null
}
]
]
}
}
Table row blocks contain the following within the table_row
property:
Property | Type | Description | Example value |
---|---|---|---|
cells | array of array of Rich text objects | Array of cell contents in horizontal display order. Each cell itself is an array of rich text objects. | [ |