View my integrations

Block object

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

object*

string

Always "block".

"block"

id*

string (UUIDv4)

Identifier for the block.

"7af38973-3787-41b3-bd75-0ed3a1edfac9"

type

string (enum)

Type of block. Possible values include "paragraph", "heading_1", "heading_2", "heading_3", "bulleted_list_item", "numbered_list_item", "to_do", "toggle", "child_page","child_database", "embed", "image", "video", "file", "pdf", "bookmark", "callout", "quote", "equation", "divider", "table_of_contents", "column", "column_list", "link_preview", "synced_block", "template", "link_to_page", "table"' "table_row", and "unsupported".

"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

has_children

boolean

Whether or not the block has children blocks nested within it.

true

{type}

Block Type Object (see below)

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

rich_text

array of rich text objects

Rich text in the paragraph block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the heading block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

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

rich_text

array of rich text objects

Rich text in the heading block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

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

rich_text

array of rich text objects

Rich text in the heading block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

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

rich_text

array of rich text objects

Rich text in the heading block.

icon

File Object or Emoji object

Page icon.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the quote block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the bulleted_list_item block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the numbered_list_item block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the to_do block.

checked

boolean (optional)

Whether the to_do is checked or not.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of rich text objects

Rich text in the toggle block.

color

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

children

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

rich_text

array of Rich text object text objects

Rich text in code block

caption

array of Rich text object text objects

Rich text in caption of the code block

language

string (enum)

Type of block. Possible values include:
"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", and "java/c/c++/c#"

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

title

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

title

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

url

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 Object

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 Object

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

File Object

File reference

caption

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 Object

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

url

string

Bookmark link

caption

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

expression

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

string (enum)

Color of the block. Possible values are: "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background".

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:

Property

Type

Description

children

array of column_list block objects

List of columns in the column_list block.

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

Column blocks contain the following information in the column property.

Property

Type

Description

children

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

rich_text

array of rich text objects

rich text in the title of the template

children

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

string (enum)

Type of this link to page object. Possible values are: "page_id", "database_id".

"page_id"

page_id

string (UUIDv4)

Identifier for a page

"7af38973-3787-41b3-bd75-0ed3a1edfac9"

database_id

string (UUIDv4)

Identifier for a database page

"7af38973-3787-41b3-bd75-0ed3a1edfac9"

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

synced_from

null

Value is always null to signify that this is an original synced block and that is not referring to another block

children

array of block objects

Any nested children blocks of the synced_block block. These blocks will be synced across this block and references to this synced_block

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

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

string (enum)

Type of this synced from object. Possible values are: "block_id".

"block_id"

block_id

string (UUIDv4)

Identifier of an original synced_block

"7af38973-3787-41b3-bd75-0ed3a1edfac9"

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

table_width

integer

Number of columns in the table. Note that this cannot be changed via the public API once a table is created.

3

has_column_header

boolean

Whether or not the table has a column header. If true, the first row in the table will appear visually distinct from the other rows.

false

has_row_header

boolean

Whether or not the table has a header row. If true, the first column in the table will appear visually distinct from the other columns.

false

children

array of table_row block objects

List of table_row children for this table.

[
{
"type": "table_row",
"table_row": {
"cells": [
[
{
"type": "text",
"text": {
"content": "column 1 content"
},
"plain_text": "column 1 content"
}
]
]
}
}
]

📘

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.

[
[
{
"type": "text",
"text": {
"content": "simple",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "simple",
"href": null
}
]
]