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": "c02fc1d3-db8b-45c5-a222-27595b15aea7",
    "parent": {
        "type": "page_id",
        "page_id": "59833787-2cf9-4fdf-8782-e53db20768a5"
    },
    "created_time": "2022-03-01T19:05:00.000Z",
    "last_edited_time": "2022-07-06T19:41:00.000Z",
    "created_by": {
        "object": "user",
        "id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
    },
    "last_edited_by": {
        "object": "user",
        "id": "ee5f0f84-409a-440f-983a-a5315961c6e4"
    },
    "has_children": false,
    "archived": false,
    "type": "heading_2",
    "heading_2": {
        "rich_text": [
            {
                "type": "text",
                "text": {
                    "content": "Lacinato kale",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "green"
                },
                "plain_text": "Lacinato kale",
                "href": null
            }
        ],
        "color": "default",
    "is_toggleable": false
    }
}

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". All heading blocks ("heading_1", "heading_2", and "heading_3") support children when the is_toggleable property is true.

📘

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.

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
    }]
  }
}

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",
    "is_toggleable": false
  }
}

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",
    "is_toggleable": false
  }
}

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",
    "is_toggleable": false
  }
}

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"
   }
}

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"
   }
}

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
    }]
  }
}

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
    }]
  }
}

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
    }]
  }
}

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
    }]
  }
}

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"
  }
}

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.

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.

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"
  }
}

Image blocks

Includes supported image urls (i.e. ending in .png, .jpg, .jpeg, .gif, .tif, .tiff, .bmp, .svg, or .heic). Note that the url property only accepts direct urls to an image. The image must be directly hosted. In other words, the url cannot point to a service that retrieves the image.

{
  "type": "image",
  //...other keys excluded
  "image": {
    "type": "external",
    "external": {
        "url": "https://website.domain/images/image.png"
    }
  }
}

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"
    }
  }
}

File blocks

{
  "type": "file",
  //...other keys excluded
  "file": {
    "type": "external",
    "external": {
        "url": "https://website.domain/files/doc.txt"
    }
  }
}

PDF blocks

{
  "type": "pdf",
  //...other keys excluded
  "pdf": {
    "type": "external",
    "external": {
        "url": "https://website.domain/files/doc.pdf"
    }
  }
}

Bookmark blocks

{
  "type": "bookmark",
  //...other keys excluded
  "bookmark": {
    
    "url": "https://website.domain"
  }
}

Bookmark block objects contain the following information within the bookmark property:

Equation blocks

{
  "type": "equation",
  //...other keys excluded
  "equation": {
    
    "expression": "e=mc^2"
  }
}

Equation block objects contain the following information within the equation property

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

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 columns. They do not contain any information within the column property. They can only be appended to column_lists.

When creating a column list block via Append block children, the column_list must have at least 2 columns, and those columns 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:

{
  "type": "column",
  //...other keys excluded
  "column": {}
}

Column blocks contain the following information in the column property.

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:

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.

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:

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:

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.

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:

📘

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: