developers.notion.com
Open in
urlscan Pro
2606:4700::6812:d238
Public Scan
Submitted URL: https://developers.notion.com/reference/block#video
Effective URL: https://developers.notion.com/reference/block
Submission: On May 22 via manual from FR — Scanned from FR
Effective URL: https://developers.notion.com/reference/block
Submission: On May 22 via manual from FR — Scanned from FR
Form analysis 0 forms found in the DOM
Text Content
Jump to Content
HomeGuidesAPI ReferenceChangelogExamples
--------------------------------------------------------------------------------
View my integrations
API Reference
View my integrations
HomeGuidesAPI ReferenceChangelogExamples
Search
CTRL-K
Notion APIIntroductionIntegration capabilitiesRequest limitsStatus
codesVersioningChanges by versionObjectsBlockPagePage propertiesDatabaseDatabase
propertiesUserCommentOtherEmoji objectFile objectParent objectRich text
objectUnfurl attribute object for Link PreviewsEndpointsAuthenticationCreate a
tokenBlocksAppend block childrenRetrieve a blockRetrieve block childrenUpdate a
blockDelete a blockPagesCreate a pageRetrieve a pageRetrieve a page property
itemUpdate page propertiesArchive a pageDatabasesCreate a databaseFilter
database entriesSort database entriesQuery a databaseRetrieve a databaseUpdate a
databaseUpdate database propertiesUsersList all usersRetrieve a userRetrieve
your token's bot userCommentsCreate commentRetrieve commentsSearchSearch by
titleSearch optimizations and limitations
All
Guides
Reference
Pages
START TYPING TO SEARCH…
JUMP TOCTRL-/
NOTION API
* Introduction
* Integration capabilities
* Request limits
* Status codes
* Versioning
* Changes by version
OBJECTS
* Block
* Page
* Page properties
* Database
* Database properties
* User
* Comment
* Other
* Emoji object
* File object
* Parent object
* Rich text object
* Unfurl attribute object for Link Previews
ENDPOINTS
* Authentication
* Create a tokenpost
* Blocks
* Append block childrenpatch
* Retrieve a blockget
* Retrieve block childrenget
* Update a blockpatch
* Delete a blockdelete
* Pages
* Create a pagepost
* Retrieve a pageget
* Retrieve a page property itemget
* Update page propertiespatch
* Archive a page
* Databases
* Create a databasepost
* Filter database entries
* Sort database entries
* Query a databasepost
* Retrieve a databaseget
* Update a databasepatch
* Update database properties
* Users
* List all usersget
* Retrieve a userget
* Retrieve your token's bot userget
* Comments
* Create commentpost
* Retrieve commentsget
* Search
* Search by titlepost
* Search optimizations and limitations
JUMP TOCTRL-/
NOTION API
* Introduction
* Integration capabilities
* Request limits
* Status codes
* Versioning
* Changes by version
OBJECTS
* Block
* Page
* Page properties
* Database
* Database properties
* User
* Comment
* Other
* Emoji object
* File object
* Parent object
* Rich text object
* Unfurl attribute object for Link Previews
ENDPOINTS
* Authentication
* Create a tokenpost
* Blocks
* Append block childrenpatch
* Retrieve a blockget
* Retrieve block childrenget
* Update a blockpatch
* Delete a blockdelete
* Pages
* Create a pagepost
* Retrieve a pageget
* Retrieve a page property itemget
* Update page propertiespatch
* Archive a page
* Databases
* Create a databasepost
* Filter database entries
* Sort database entries
* Query a databasepost
* Retrieve a databaseget
* Update a databasepatch
* Update database properties
* Users
* List all usersget
* Retrieve a userget
* Retrieve your token's bot userget
* Comments
* Create commentpost
* Retrieve commentsget
* Search
* Search by titlepost
* Search optimizations and limitations
BLOCK
A block object represents a piece of content within Notion. The API translates
the headings, toggles, paragraphs, lists, media, and more that you can interact
with in the Notion UI as different block type objects.
For example, the following block object represents a Heading 2 in the Notion UI:
Example Block Object
{
"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
}
}
Use the Retrieve block children endpoint to list all of the blocks on a page.
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.
FieldTypeDescriptionExample valueobject*stringAlways "block"."block"id*string
(UUIDv4)Identifier for the
block."7af38973-3787-41b3-bd75-0ed3a1edfac9"parentobjectInformation about the
block's parent. See Parent object.{ "type": "block_id", "block_id":
"7d50a184-5bbe-4d90-8f29-6bec57ed817b" }typestring (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"
- "link_to_page"
- "numbered_list_item"
- "paragraph"
- "pdf"
- "quote"
- "synced_block"
- "table"
- "table_of_contents"
- "table_row"
- "template"
- "to_do"
- "toggle"
- "unsupported"
- "video""paragraph"created_timestring (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_byPartial UserUser who created the
block.{"object": "user","id":
"45ee8d13-687b-47ce-a5ca-6e2e45548c4b"}last_edited_timestring (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_byPartial UserUser who
last edited the block.{"object": "user","id":
"45ee8d13-687b-47ce-a5ca-6e2e45548c4b"}archivedbooleanThe archived status of the
block.falsehas_childrenbooleanWhether or not the block has children blocks
nested within it.true{type}block type objectAn 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_toggleable property is true
* Heading 2, when the is_toggleable property is true
* Heading 3, when the is_toggleable property is true
* 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 of type. Under the key
is an object with type-specific block information.
BOOKMARK
Bookmark block objects contain the following information within the bookmark
property:
FieldTypeDescriptioncaptionarray of rich text objects textThe caption for the
bookmark.urlstringThe link for the bookmark.
Example Bookmark block object
{
//...other keys excluded
"type": "bookmark",
//...other keys excluded
"bookmark": {
"caption": [],
"url": "https://companywebsite.com"
}
}
BREADCRUMB
Breadcrumb block objects do not contain any information within the breadcrumb
property.
Example Breadcrumb block object
{
//...other keys excluded
"type": "breadcrumb",
//...other keys excluded
"breadcrumb": {}
}
BULLETED LIST ITEM
Bulleted list item block objects contain the following information within the
bulleted_list_item property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text in the
bulleted_list_item block.colorstring (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"childrenarray of block objectsThe nested child blocks (if
any) of the bulleted_list_item block.
Example Bulleted list item block object
{
//...other keys excluded
"type": "bulleted_list_item",
//...other keys excluded
"bulleted_list_item": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
// ..other keys excluded
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
CALLOUT
Callout block objects contain the following information within the callout
property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text in the
callout block.iconobjectAn emoji or file object that represents the callout's
icon. If the callout does not have an icon.colorstring (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"
Example Callout block object
{
//...other keys excluded
"type": "callout",
// ..other keys excluded
"callout": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
// ..other keys excluded
}],
"icon": {
"emoji": "⭐"
},
"color": "default"
}
}
CHILD DATABASE
Child database block objects contain the following information within the
child_database property:
FieldTypeDescriptiontitlestringThe plain text title of the database.
Example Child database block
{
//...other keys excluded
"type": "child_database",
//...other keys excluded
"child_database": {
"title": "My database"
}
}
> 📘
>
> CREATING AND UPDATING CHILD_DATABASE BLOCKS
>
> To 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 the child_page
property:
FieldTypeDescriptiontitlestringThe plain text title of the page.
Example Child page block object
{
//...other keys excluded
"type": "child_page",
//...other keys excluded
"child_page": {
"title": "Lacinato kale"
}
}
> 📘
>
> CREATING AND UPDATING CHILD_PAGE BLOCKS
>
> To 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 the code property:
FieldTypeDescriptioncaptionarray of Rich text object text objectsThe rich text
in the caption of the code block.rich_textarray of Rich text object text
objectsThe 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.
Example Code block object
{
//...other keys excluded
"type": "code",
//...other keys excluded
"code": {
"caption": [],
"rich_text": [{
"type": "text",
"text": {
"content": "const a = 3"
}
}],
"language": "javascript"
}
}
COLUMN LIST AND COLUMN
Column lists are parent blocks for columns. They do not contain any information
within the column_list property.
Example Column list block object
{
//...other keys excluded
"type": "column_list",
//...other keys excluded
"column_list": {}
}
Columns are parent blocks for any block types listed in this reference except
for other columns. They do not contain any information within the column
property. They can only be appended to column_lists.
Example Column object
{
//...other keys excluded
"type": "column",
//...other keys excluded
"column": {}
}
When creating a 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 a column_list:
1. Get the column_list ID from a query to Retrieve block children for the
parent page.
2. Get the column children from a query to Retrieve block children for the
column_list.
3. Get the content in each individual column from a query to Retrieve block
children for the unique column ID.
DIVIDER
Divider block objects do not contain any information within the divider
property.
Example Divider block object
{
//...other keys excluded
"type": "divider",
//...other keys excluded
"divider": {}
}
EMBED
Embed block objects include information about another website displayed within
the Notion UI. The embed property contains the following information:
FieldTypeDescriptionurlstringThe link to the website that the embed block
displays.
Example Embed block object
{
//...other keys excluded
"type": "embed",
//...other keys excluded
"embed": {
"url": "https://companywebsite.com"
}
}
> 🚧
>
> DIFFERENCES IN EMBED BLOCKS BETWEEN THE NOTION APP AND THE API
>
> The Notion app uses a 3rd-party service, iFramely, 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 iFramely.
>
> We chose not to call iFramely 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 iFramely could actually cause us to 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.
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
the equation property:
FieldTypeDescriptionexpressionstringA KaTeX compatible string.
Example Equation object
{
//...other keys excluded
"type": "equation",
//...other keys excluded
"equation": {
"expression": "e=mc^2"
}
}
FILE
File block objects contain the following information within the file property:
FieldTypeDescriptioncaptionarray of rich text objectsThe caption of the file
block.type"file"
"external"A constant string.filefile objectA file object that details
information about the file contained in the block.
Example File object
{
//...other keys excluded
"type": "file",
//...other keys excluded
"file": {
"caption": [],
"type": "external",
"external": {
"url": "https://companywebsite.com/files/doc.txt"
}
}
}
HEADINGS
All heading block objects, heading_1, heading_2, and heading_3, contain the
following information within their corresponding objects:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text of the
heading.colorstring (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_toggleablebooleanWhether 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.
Example Heading 1 block object
{
//...other keys excluded
"type": "heading_1",
//...other keys excluded
"heading_1": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"is_toggleable": false
}
}
Example Heading 2 block object
{
//...other keys excluded
"type": "heading_2",
//...other keys excluded
"heading_2": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"is_toggleable": false
}
}
Example Heading 3 block object
{
//...other keys excluded
"type": "heading_3",
//...other keys excluded
"heading_3": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default",
"is_toggleable": false
}
}
IMAGE
Image block objects contain a file object detailing information about the image.
Example Image block object
{
//...other keys excluded
"type": "image",
//...other keys excluded
"image": {
"type": "external",
"external": {
"url": "https://website.domain/images/image.png"
}
}
}
SUPPORTED IMAGE TYPES
The image must be directly hosted. In other words, the url cannot point to a
service that retrieves the image. The following image types are supported:
* .bmp
* .gif
* .heic
* .jpeg
* .jpg
* .png
* .svg
* .tif
* .tiff
LINK PREVIEW
Link Preview block objects contain the originally pasted url:
Example Link preview block object
{
//...other keys excluded
"type": "link_preview",
//...other keys excluded
"link_preview": {
"url": "https://github.com/example/example-repo/pull/1234"
}
}
> 🚧
>
> The link_preview block can only be returned as part of a response. The API
> does not support creating or appending link_preview blocks.
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:
FieldTypeDescriptiontype"database"
"date"
"link_preview"
"page"
"user"A constant string representing the type of the mention."database"
"date"
"link_preview"
"page"
"user"objectAn object with type-specific information about the mention.
Example Mention object
{
//...other keys excluded
"type": "page",
"page": {
"id": "3c612f56-fdd0-4a30-a4d6-bda7d7426309"
}
}
NUMBERED LIST ITEM
Numbered list item block objects contain the following information within the
numbered_list_item property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the numbered_list_item block.colorstring (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"childrenarray of block objectsThe nested child blocks (if
any) of the numbered_list_item block.
Example Numbered list item block
{
//...other keys excluded
"type": "numbered_list_item",
"numbered_list_item": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Finish reading the docs",
"link": null
}
}
],
"color": "default"
}
}
PARAGRAPH
Paragraph block objects contain the following information within the paragraph
property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the paragraph block.colorstring (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"childrenarray of block objectsThe nested child blocks (if
any) of the paragraph block.
Example Paragraph block object
{
//...other keys excluded
"type": "paragraph",
//...other keys excluded
"paragraph": {
"rich_text": [{
"type": "text",
"text": {
"content": "Lacinato kale",
"link": null
}
}],
"color": "default"
}
Example Paragraph block object with a child Mention block object
{
//...other keys excluded
"type": "paragraph",
"paragraph":{
"rich_text": [
{
"type": "mention",
"mention": {
"type": "date",
"date": {
"start": "2023-03-01",
"end": null,
"time_zone": null
}
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": "2023-03-01",
"href": null
},
{
"type": "text",
"text": {
"content": " ",
"link": null
},
"annotations": {
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"code": false,
"color": "default"
},
"plain_text": " ",
"href": null
}
],
"color": "default"
}
}
PDF
A PDF block object represents a PDF that has been embedded within a Notion page.
It contains the following fields:
PropertyTypeDescriptioncaptionarray of rich text objectsA caption, if provided,
for the PDF block.type"external"
"file"A constant string representing the type of PDF. file indicates a
Notion-hosted file, and external represents a third-party link.external
filefile objectAn object containing type-specific information about the PDF.
JSON
{
//...other keys excluded
"type": "pdf",
//...other keys excluded
"pdf": {
"type": "external",
"external": {
"url": "https://website.domain/files/doc.pdf"
}
}
}
QUOTE
Quote block objects contain the following information within the quote property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the quote block.colorstring (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"childrenarray of block objectsThe nested child blocks, if
any, of the quote block.
Example Quote block
{
//...other keys excluded
"type": "quote",
//...other keys excluded
"quote": {
"rich_text": [{
"type": "text",
"text": {
"content": "To be or not to be...",
"link": null
},
//...other keys excluded
}],
//...other keys excluded
"color": "default"
}
}
SYNCED BLOCK
Similar to the Notion UI, there are two versions of a synced_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 the
synced_block property:
FieldTypeDescriptionsynced_fromnullThe value is always null to signify that this
is an original synced block that does not refer to another block.childrenarray
of block objectsThe nested child blocks, if any, of the synced_block block.
These blocks will be mirrored in the duplicate synced_block.
Example Original synced block
{
//...other keys excluded
"type": "synced_block",
"synced_block": {
"synced_from": null,
"children": [
{
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Callout in synced block"
}
}
]
}
}
]
}
}
DUPLICATE SYNCED BLOCK
Duplicate synced block objects contain the following information within the
synced_from object:
FieldTypeDescriptiontypestring (enum)The type of the synced from object.
Possible values are:
- "block_id"block_idstring (UUIDv4)An identifier for the original synced_block.
Example Duplicate synced block object
{
//...other keys excluded
"type": "synced_block",
"synced_block": {
"synced_from": {
"block_id": "original_synced_block_id"
}
}
}
> 🚧
>
> The API does not supported updating synced block content.
TABLE
Table block objects are parent blocks for table row children. Table block
objects contain the following fields within the table property:
FieldTypeDescriptiontable_widthintegerThe number of columns in the table.
Note that this cannot be changed via the public API once a table is
created.has_column_headerbooleanWhether the table has a column header. If true,
then the first row in the table appears visually distinct from the other
rows.has_row_headerbooleanWhether the table has a header row. If true, then the
first column in the table appears visually distinct from the other columns.
Example Table block object
{
//...other keys excluded
"type": "table",
"table": {
"table_width": 2,
"has_column_header": false,
"has_row_header": false
}
}
> 🚧
>
> TABLE_WIDTH 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. Calls to the Update block endpoint to update table_width fail.
TABLE ROWS
Follow these steps to fetch the table_rows of a table:
1. Get the table ID from a query to Retrieve block children for the parent
page.
2. Get the table_rows from a query to Retrieve block children for the table.
A table_row block object contains the following fields within the table_row
property:
PropertyTypeDescriptioncellsarray of array of rich text objectsAn array of cell
contents in horizontal display order. Each cell is an array of rich text
objects.
Example Table row block object
{
//...other keys excluded
"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
}
]
]
}
}
> 📘
>
> 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 the
table_of_contents property:
PropertyTypeDescriptioncolorstring (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"
Example Table of contents block object
{
//...other keys excluded
"type": "table_of_contents",
"table_of_contents": {
"color": "default"
}
}
TEMPLATE
> ❗️
>
> DEPRECATION NOTICE
>
> As of March 27, 2023 creation of template blocks will no longer be supported.
Template blocks represent template buttons in the Notion UI.
Template block objects contain the following information within the template
property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the title of the template.childrenarray of block objectsThe nested child
blocks, if any, of the template block. These blocks are duplicated when the
template block is used in the UI.
Example Template block object
{
//...other keys excluded
"template": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Add a new to-do",
"link": null
},
"annotations": {
//...other keys excluded
},
"plain_text": "Add a new to-do",
"href": null
}
]
}
}
TO DO
To do block objects contain the following information within the to_do property:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the To do block.checkedboolean (optional)Whether the To do is
checked.colorstring (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"childrenarray of block objectsThe nested child blocks, if
any, of the To do block.
Example To do block object
{
//...other keys excluded
"type": "to_do",
"to_do": {
"rich_text": [{
"type": "text",
"text": {
"content": "Finish Q3 goals",
"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:
FieldTypeDescriptionrich_textarray of rich text objectsThe rich text displayed
in the Toggle block.colorstring (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"childrenarray of block objectsThe nested child blocks, if
any, of the Toggle block.
Toggle Block
{
//...other keys excluded
"type": "toggle",
"toggle": {
"rich_text": [{
"type": "text",
"text": {
"content": "Additional project details",
"link": null
}
//...other keys excluded
}],
"color": "default",
"children":[{
"type": "paragraph"
// ..other keys excluded
}]
}
}
VIDEO
Video block objects contain a file object detailing information about the image.
Example Video block object
{
"type": "video",
//...other keys excluded
"video": {
"type": "external",
"external": {
"url": "https://companywebsite.com/files/video.mp4"
}
}
}
SUPPORTED VIDEO TYPES
* .amv
* .asf
* .avi
* .f4v
* .flv
* .gifv
* .mkv
* .mov
* .mpg
* .mpeg
* .mpv
* .mp4
* .m4v
* .qt
* .wmv
* YouTube video links that include embed or watch.
E.g. https://www.youtube.com/watch?v=[id], https://www.youtube.com/embed/[id]
Updated 7 days ago
--------------------------------------------------------------------------------
Changes by version
Page
Did this page help you?
Yes
No
Updated 7 days ago
--------------------------------------------------------------------------------
Changes by version
Page
Did this page help you?
Yes
No
* Table of Contents
* * Keys
* Block type objects
* Bookmark
* Breadcrumb
* Bulleted list item
* Callout
* Child database
* Child page
* Code
* Column list and column
* Divider
* Embed
* Equation
* File
* Headings
* Image
* Link Preview
* Mention
* Numbered list item
* Paragraph
* PDF
* Quote
* Synced block
* Table
* Table of contents
* Template
* To do
* Toggle blocks
* Video
1. Notion API
2. Introduction
3. Integration capabilities
4. Request limits
5. Status codes
6. Versioning
7. Changes by version
1. Objects
2. Block
3. Page
4. Page properties
5. Database
6. Database properties
7. User
8. Comment
9. Other
10. Emoji object
11. File object
12. Parent object
13. Rich text object
14. Unfurl attribute object for Link Previews
1. Endpoints
2. Authentication
3. Create a tokenpost
4. Blocks
5. Append block childrenpatch
6. Retrieve a blockget
7. Retrieve block childrenget
8. Update a blockpatch
9. Delete a blockdelete
10. Pages
11. Create a pagepost
12. Retrieve a pageget
13. Retrieve a page property itemget
14. Update page propertiespatch
15. Archive a page
16. Databases
17. Create a databasepost
18. Filter database entries
19. Sort database entries
20. Query a databasepost
21. Retrieve a databaseget
22. Update a databasepatch
23. Update database properties
24. Users
25. List all usersget
26. Retrieve a userget
27. Retrieve your token's bot userget
28. Comments
29. Create commentpost
30. Retrieve commentsget
31. Search
32. Search by titlepost
33. Search optimizations and limitations
1. Notion API
2. Introduction
3. Integration capabilities
4. Request limits
5. Status codes
6. Versioning
7. Changes by version
1. Objects
2. Block
3. Page
4. Page properties
5. Database
6. Database properties
7. User
8. Comment
9. Other
10. Emoji object
11. File object
12. Parent object
13. Rich text object
14. Unfurl attribute object for Link Previews
1. Endpoints
2. Authentication
3. Create a tokenpost
4. Blocks
5. Append block childrenpatch
6. Retrieve a blockget
7. Retrieve block childrenget
8. Update a blockpatch
9. Delete a blockdelete
10. Pages
11. Create a pagepost
12. Retrieve a pageget
13. Retrieve a page property itemget
14. Update page propertiespatch
15. Archive a page
16. Databases
17. Create a databasepost
18. Filter database entries
19. Sort database entries
20. Query a databasepost
21. Retrieve a databaseget
22. Update a databasepatch
23. Update database properties
24. Users
25. List all usersget
26. Retrieve a userget
27. Retrieve your token's bot userget
28. Comments
29. Create commentpost
30. Retrieve commentsget
31. Search
32. Search by titlepost
33. Search optimizations and limitations
The all-in-one workspace for your notes, tasks, wikis, and databases.
©2022 Notion Labs, Inc.
Terms & Privacy
DEVELOPERS
Guides API reference My integrations Developer terms
NOTION
Product Teams Enterprise Blog Careers
COMMUNITY
Slack Stack Overflow Twitter