Historical changelog

• The Working with databases guide was revised to improve its readability and to make additional resources easier to find.
• Notion’s Postman collection for the API was updated. Be sure to pull recent changes into your forked version.
• A reminder was added to the Comments endpoints to update integration capabilities for comments prior to using the endpoints. (Read/write comment capabilities are off by default and can be turned on in the integration dashboard.)
• General clean-up and improvements, including code formatting.

• The Build your first integration guide was rewritten with new demo code to help developers learn how to use Notion’s API even faster.
  • A new sample app was added to the Notion SDK for JavaScript /examples directory. This completed sample app is referenced in the new Build your first integration guide.
• The description for the block_id path parameter was updated for the Append block children endpoint to indicate that a block ID or page ID can be used.
• A clarification was added to documentation for retrieving/updating database properties: If a property is based on a relation to another database, the related database also needs to be shared with the integration.
• A clarification was added to documentation for querying databases. When filtering a multi-select property, the contains field will filter for exact matches for the string provided.
• The Working with comments guide was updated with additional examples to distinguish between creating page comments and inline discussion comments.
  • The Create a comment endpoint description now links to the Working with comments guide to help developers find additional resources faster.
• If you haven’t already, join our Notion Devs Slack group to learn from other developers building with the public API.

​

Notice for an upcoming Public API change

​

We will soon be rolling out changes to the Formulas property (Formulas 2.0), and as such, we will be making a change to the Notion Public API.

​

What do you need to know?

• On write via the Public API (create or update database endpoints), Notion will support using the old format as a Public API input in the formula property schema indefinitely and will support writing in the new format.
• Database objects returned via the Public API will have the new formulas 2.0 format.

// Old format
"Updated price": {
  "id": "YU%7C%40",
  "name": "Updated price",
  "type": "formula",
  "formula": {
    "expression": "prop(\"Price\") * 2"
  }
}

// New format (upcoming)
"Updated price": {
  "id": "YU%7C%40",
  "name": "Updated price",
  "type": "formula",
  "formula": {
      "expression": "{{notion:block_property:BtVS:00000000-0000-0000-0000-000000000000:8994905a-074a-415f-9bcf-d1f8b4fa38e4}}/2"
  }
}

​

Why is this happening?

1. It’s easier to write formulas.
2. Formula outputs look and feel more native to Notion.
3. The formula language can fulfill more specific needs.

​

What do you need to do?

• Notion is excited to announce our Technology Partnership Program. 🎉 This program is open to companies who have built a public integration (including Link Previews) and are interested in improving and scaling their integration with Notion’s support. If you think your integration and company could be a fit, learn more and apply here.
• We’ve updated our API reference docs to include information on Notion’s wiki databases and verified pages. Updates include:
  • An overview on wikis in the guide to working with databases.
  • The verification page property was added to the Page properties documentation.
  • The Create a database and Query a database endpoint documentation was updated to reflect API changes related to wikis. Namely, that querying wiki databases can return both Page and Database objects.
• The Error codes section in the Status code page was updated to include examples of the "message" returned with each type of API error, as well as descriptions of the issue each error code represents.
• A number of sample cURL commands in our docs were still using an old Notion Version in their headers. These have all been updated.
• A clarification was added to the Authorization guide that the Notion Version is always required in public API request headers.

• A new integration example was added to the Notion SDK for JavaScript repo. This example shows how to get the plain text from any block type currently supported by the public API.
• The new unique ID page property was added to the Page properties documentation. When used, the unique ID (unique_id) auto-increments for every new page created in a database. An optional prefix can be included that will be applied to the ID values.

• Workspace Owners can now see all internal integrations created in a workspace via the integration dashboard. This includes integrations created by themselves and other Workspace Owners. We’ve included this information in our Getting Started guide.
• A Notion SDK for JavaScript code sample was added to the Create a database endpoint documentation.

• We updated our Getting started guide to help developers who are new to the public API better understand how the API relates to integrations.
• The Block object docs were updated with a tip on how to embed Vimeo links in a Notion page via the API.
• A new after parameter has been added to the Append block children endpoint. Developers can now specific where to append a new block, instead of appending it to the end of a parent block by default.
  cURL

  Report incorrect code

  Copy

  Ask AI

  curl -X PATCH https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children \
    -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
    -H "Content-Type: application/json" \
    -H "Notion-Version: 2022-06-28" \
    --data '{
      "children": [
      ...
      }
    ], after: "<block_id_to_append_after>"
  }'
  
• The Authorization guide had a clarification added to help developers find the resources they need for Link Preview integrations.
• The new public_url property was added to the docs. When a page or database has been shared publicly, the response body will include a public_url value.
  JSON

  Report incorrect code

  Copy

  Ask AI

  {
    "object": "page",
    "id": "<id>",
    "created_time": "2023-06-02T19:54:00.000Z",
    "last_edited_time": "2023-06-02T23:04:00.000Z",
    "created_by": { ... },
    "last_edited_by": { ... },
    "cover": null,
    "icon": null,
    "parent": { ... },
    "archived": false,
    "properties": { ... },
    "url": "<url>",
    "public_url": "<public-url>"
  }
  
• The Retrieve block children endpoint documentation was updated to help developers who are new to the public API better understand the endpoint’s functionality.
• The Retrieve a block endpoint documentation was updated with some additional information related to working with page content.
• The invalid_grant code was added to our Status codes documentation. This code is returned when the authorization grant (e.g. token) provided is invalid. For example, a status code 400 with an invalid_grant code will be returned when the token provided has expired.
• The Rich text documentation was updated with additional information on what rich text is and how the Notion uses it.

• Our guides and docs related to Link Preview integrations have been updated to help developers find the information they need faster. Improvements have been made to the following guides and API reference docs:
  • Getting started guide
  • Introduction to Link Previews guide
  • Building a Link Preview integration guide
  • Unfurl attribute object docs
• We added more information about the plain_text property found in the rich_text object. Learn more about rich text in our Rich text object docs.
• The docs related to filtering and sorting database queries now have more code examples for developers building integrations with the Notion SDK for JavaScript.
• We reorganized the REST API reference navigation bar after removing the “Other” section to make its child pages easier to find.

• The Query a database and Filter database entries docs were updated with additional code examples of passing single and multiple filters.
• The Working with comments guide was updated to clarify how to retrieve and add comments using the REST API.
• The references docs for rollup page properties, as well as the Retrieve a page property and Retrieve a page endpoints were updated with additional information related to limitations. In cases where a page property — like a rollup — has more than 25 references, the Retrieve a page property endpoint must be used to receive a complete response.
• An outdated Changelog URL now redirects to this Changelog page to help avoid confusion.

• We added a database schema size recommendation of 50KB to our docs to help developers manage their database query performance. It is strongly recommended that developers keep their schema size under this number.
• The Update a database page was updated to improve readability. Additional information on how this endpoint differs from related endpoints was also added to help developers better navigate the REST API docs.
• The Query a database page was updated with additional information about the filter_properties query parameter. When used with the REST API, this query parameter is passed as a string, like so:

https://api.notion.com/v1/databases/[database_id]/query?filter_properties=[property_id_1]&filter_properties=[property_id_2]

notion.databases.query({
	database_id: 'databaseID',
	filter_properties: ["propertyID1", "propertyID2"]
})

• Docs that mention the redirect_uri — a value used with public integrations — were updated to clarify when this value is required. Refer to the Create a token page for a complete description.
• The video block-type was updated on the Block Object page to clarify accepted video types. YouTube URLs that contain watch or embed are supported video types.
• The Append a block page content was reorganized to improve readability.

• The Build a Link Preview integration guide was updated to reflect a change regarding how link previews are enabled in the integration dashboard.
• The versioning page was updated to clarify that the Notion-Version header is required in Notion REST API requests.
• The parent object page and API reference docs for database POST requests and blocks PATCH requests were updated to better explain how parenting rules work.
• The Integration guide was updated with more links to help developers find resources faster.
• Number database properties now support the Peruvian sol as a currency format. To use it, set "peruvian_sol" as the value for a number’s format field when creating or updating a database property or schema.
• General docs housekeeping, such reducing the number of callouts in our API reference docs to improve the readability.

• Our developer community Slack invite link was updated. Join here to connect with other developers building with the Notion API.
• The Authorization guide was updated to include more information on creating integrations, adding templates to public integrations, and more code examples to get you started, faster.
• We’ve added more code examples to our API reference docs, including Archive a page and Authentication.
• General docs housekeeping, such reducing the number of callouts in our API reference docs to improve the readability.

​

Fixes and improvements

• You can now update rollup database properties via the API. To programmatically update a rollup property, send a PATCH to Update a database that specifies the change in the properties body param.

​

Fixes and improvements

• Stay tuned!

​

New things

• Added a token Refresh button to the settings page for internal integrations. Click Refresh to generate a new token for your internal integration.

​

New things

• Shipped detailed docs for Link Previews including an overview, getting started guide, and reference materials.

​

Fixes and improvements

• The Retrieve a Page endpoint can now return specific page property values when you include the filter_properties path param.
• You can now request specific page property values from a database by passing filter_properties in the request body to the Query a database endpoint.

​

New things

• Happy 2023! For a sneak peek of what we’ll be up to this year, check out our updated platform roadmap.

​

Fixes and improvements

• Updated the Append block children and Retrieve block children endpoints to specific supported block types to create a more consistent dev experience. The endpoints now throw an error if the block type in the request does not support children.

​

New things

• Built a ✨Glitch ✨ demo that updates Notion tasks when a linked GitHub PR is closed or merged. Give it a spin!

• We added a this_week filter for database queries. You can now search for database entries where the "date", "created_time", or "last_edited_time" property value falls within the current week. Refer to the date filter condition docs for details.

• Number database properties now support the Singapore dollar as a currency format. To use it, set "singapore_dollar" as the value for a number’s format field when creating or updating a database property or schema.

• You can now add a Notion template option to a public integration from the integration’s settings page. For details on what the permissions flow looks like for users who opt in to the template, refer to the Authorization guide.

• A relation property value now includes a has_more property when returned by the Retrieve a page endpoint. has_more is true if the relation has more than 25 page references. Otherwise, has_more is false.
• We added a workspace_name property to bot user objects. If the bot  owner.type is "workspace", then workspace.name identifies the name of the workspace that owns the bot. If the owner.type is "user", then workspace.name is null.

• Fixed a bug where date mentions ended in a → character even if they only represented a single date, not a date range.
• Added an Authorization URL field to the public integration form. You can now click to copy the URL that allows users to authorize your integration (read more in the Authorization guide).
• Corrected an error that caused the getProperty endpoint to return only one item if the property_id belonged to a multi-item Files page property.

​

Version 2022-06-28 includes page property types and values

​

Features

• The public API now supports the following functionality for status properties:
  • Reading and updating status properties on pages (read more)
  • Reading, but not updating, status property configuration on databases (read more)
  • Filtering or sorting by status properties when querying databases (read more)
• header_1, header_2, and header_3 blocks now have an is_toggleable property, to better indicate whether they are heading toggle blocks. (read more)
  • Headings can be togglified and un-togglified by setting is_toggleable to true or false, but note that all the children inside the toggle must be removed before it can be untogglified.

​

Features

• Added support for reading and writing page-level comments in the API.

​

Comments API

• Read comments from a page or block.
• Add a comment to a page.
• Add a comment to an existing discussion thread on a block.

​

Features

• Released a new version of the API, 2022-06-28. Previous versions of the API are still supported. Read more about the new version here.
• Created a new template repository for getting started with the Notion API and the official SDK. Find it here.

​

Bug fixes and performance improvements

• Exported many more named types for API response objects in the official SDK.
• Fixed a bug in the official SDK where some API requests would not work due a capitalization issue. (This was a community-submitted PR; thank you @dvanoni!)

​

Releasing Notion-Version 2022-06-28

• Page properties must be retrieved using the page properties endpoint.
• Parents are now always direct parents; a parent field has been added to block.
• Database relations have a type of single_property and dual_property.

​

Page properties must be retrieved using the page properties endpoint

"properties": {
    "Name": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Avocado",
            "link": null
          },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Avocado",
          "href": null
        }
      ]
   }
}

"properties": {
    "Name": {
      "id": "title"
   }
}

​

Parents are now always direct parents; a parent field has been added to block

​

Database relations have a type of single_property and dual_property

​

New version of the JavaScript SDK

​

Features

• Added limited readonly support for database status properties. Read more about status properties here.
  • Status property values are returned in the Retrieve a page endpoint. See Property values for more information.
  • Status property configuration is not supported yet. See Property object for more information.

​

Bug Fixes

• Added a validation for adding new rollup properties that prevents creating a rollup of another rollup.

​

Features

• Added support for creating inline databases with is_inline. Read more here.
• Added support for reading and writing database descriptions with the description field. Read more here.

​

Bug fixes and performance improvements

• The public API once again supports inlinemailto links in rich text.

​

Bug fixes and performance improvements

• We now validate URLs used to create inline text links in the public API. For more details on inline links in rich text, see the Rich text object documentation.
• The Search endpoint now returns fuzzier matches, including plurals and different verb tenses. This corresponds to fuzzier matches while searching in the Notion app and should result in more search results overall for any given query.
• Fixed a bug where the integration page at integrations dashboard wouldn’t load.

​

Link Preview APIs

​

Bug fixes and performance improvements

• We’ve shipped a couple of improvements under the hood to make the search and query database endpoints faster. We’re actively looking into 500s and timeouts on the query database endpoint in particular.
• Fixed a bug in the OAuth page picker where Shared pages wouldn’t load until the workspace switcher was clicked

​

Bug fixes and performance improvements

• Fixed a bug where some rollups and relations appeared empty when they shouldn’t have.
• Fixed a bug in the query database endpoint where an invalid pagination cursor was being returned.

​

Features

• You can now filter databases on the created at and last edited at timestamps, even if they don’t have a corresponding property of that type. Read more here.
• A Retry-After response header is now being sent with rate limited request responses. The value of this field is set as an integer number of seconds (in decimal). Requests made after waiting this minimum amount of time should not be rate limited. Read more about our rate limits here.

​

Bug fixes and performance improvements

• Stopped throwing an error when rendering property formulas that hadn’t been set up yet in the Retrieve a page property item endpoint. These formulas now return null values.

​

Query a database endpoint supports filtering by timestamp

{
    "filter": {
        "timestamp": "created_time",
        "created_time": {
          "past_week": {}
        }
    }
}

{
    "filter": {
        "timestamp": "last_edited_time",
        "last_edited_time": {
          "after": "2021-05-10"
        }
    }
}

​

Features

• Block colors are now supported in the API! Read more about it here.

​

Bug fixes and performance improvements

• Rich text objects now properly include template mentions. Read more about this type of text object here.

​

Block colors are now supported in the API

{
    "object": "block",
    "id": "79bc0ae2-b002-4ecd-92db-870354734aaf",
    "created_time": "2022-03-03T22:49:00.000Z",
    "last_edited_time": "2022-03-03T22:49:00.000Z",
    "created_by": {
        "object": "user",
        "id": "914ff1b3-45c7-48dc-b2c2-be37d21e7695"
    },
    "last_edited_by": {
        "object": "user",
        "id": "914ff1b3-45c7-48dc-b2c2-be37d21e7695"
    },
    "has_children": false,
    "archived": false,
    "type": "callout",
    "callout": {
        "rich_text": [
            {
                "type": "text",
                "text": {
                    "content": "This block has color!",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "default"
                },
                "plain_text": "This block has color!",
                "href": null
            }
        ],
        "icon": {
            "type": "emoji",
            "emoji": "💡"
        },
        "color": "green_background"
    }
}

​

Updated Developers Terms

​

Features

• We now have a roadmap, so you have a better sense of what we’ll be building next.
• We released a new version of the API, 2022-02-22. This version makes our requests and responses more consistent across properties, blocks, and filters, and officially deprecates the list databases endpoint. Read more here.
• We now show the public API status independently of Notion’s status on https://status.notion.so/.
• Added created_by and edited_by to pages, blocks, and databases, and added archived to databases. Read more here.
• Added new ways for admins of Enterprise workspaces to view and control the integrations installed in their workspaces. Read more here.
• Added more information to paginated responses to make it easier to fetch complete responses for complex property types. Read more here.

​

Bug fixes and performance improvements

• Fixed a bug where pages and databases with archived (i.e. trashed) ancestors would show archived: false. They now show archived: true because they are, in fact, archived.
• Improved API performance when rendering users who are members in the space. This affects all user, block, and page-related endpoints since users can be mentioned in both page properties and rich text.
• Added a message about sharing relevant pages and databases with a bot in the 404 not found error message. We found that this was one of the more common reasons for API users to get a 404 when calling the API.
• Fixed a bug where bots could be given a more restrictive “Can edit content” access on child databases, which prevented some bots with write access from being able to update the database schema.
• Fixed a bug where user mentions failed with “user not found” when creating new blocks, even if those users should have been visible to the bot.
• Fixed a bug where malformed properties in a single page would cause an entire request to the query database endpoint to fail.
• Fixed a bug where it was possible to update a page/database in the trash. Attempting to update a trashed page or database now returns a validation error.
• Fixed a bug in the get page property endpoint where retrieving a rollup property which referenced a relation containing pages the bot did not have access to skipped those pages and returned an incorrect result. We now return a validation error.
• Fixed a bug in the get page property endpoint where retrieving a formula property whose depth exceeds what we can compute in the API simply returned the wrong value. We now return a validation error.

​

Created by and last edited by properties in Block, Page and Database objects

{
  "object": "page",
  "id": "e722caec-ae02-4a41-9bbd-286f65f8dca4",
  "created_time": "2022-02-15T21:24:00.000Z",
  "last_edited_time": "2022-02-17T22:40:00.000Z",
  "created_by": {
    "object": "user",
    "id": "71e95936-2737-4e11-b03d-f174f6f13087"
  },
  "last_edited_by": {
    "object": "user",
    "id": "5ba97cc9-e5e0-4363-b33a-1d80a635577f"
  },
  "cover": null,
  "icon": null,
  "parent": {
    "type": "page_id",
    "page_id": "a7e32210-c151-4b96-8b94-ea659b1e8e4f"
  },
  "archived": false,
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Tasks",
            "link": null
          },
          "annotations": {
            "bold": false,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Tasks",
          "href": null
        }
      ]
    }
  },
  "url": "https://notion.so/Tasks-e722caecae024a419bbd286f65f8dca4"
}

​

Releasing Notion-Version 2022-02-22

• text in blocks has been renamed to rich_text, to be consistent with the database property type.
• Query database filter changes:
  • phone and text are no longer supported in query database filters when filtering by phone_number and rich_text properties. Use phone_number and rich_text instead.
  • rollup query database filters no longer accept the text keyword. Use rich_text instead.
  • formula query database filters no longer accept the text keyword. Use string instead.
• property_item objects now return a type, next_url, and id.
• Deprecated the List Databases API endpoint.

​

The text property in content blocks has been renamed to rich_text

{
  "type": "paragraph",
  //...other keys excluded
  "paragraph": {
    "text": [{
      "type": "text",
      "text": {
        "content": "Lacinato kale",
        "link": null
      }
    }]
  }
}

{
  "type": "paragraph",
  //...other keys excluded
  "paragraph": {
    "rich_text": [{
      "type": "text",
      "text": {
        "content": "Lacinato kale",
        "link": null
      }
    }]
  }
}

​

Query database filter changes

{
	"filter": {
		"and": [
			{
				"property": "Phone number",
				"phone": {
					"equals": "1112223333"
				}
			}
		]
	}
}

{
	"filter": {
		"and": [
			{
				"property": "Phone number",
				"phone_number": {
					"equals": "1112223333"
				}
			}
		]
	}
}

"rollup property": {
	"id": "~%5Bw%5C",
	"type": "rollup",
	"rollup": {
		"type": "array",
		"array": [
			{
				"type": "rich_text",
				"rich_text": [
					{
						"type": "text",
						"text": {
							"content": "update text 2",
							"link": null
						},
						"annotations": {
							"bold": true,
							"italic": false,
							"strikethrough": false,
							"underline": false,
							"code": false,
							"color": "red"
						},
						"plain_text": "update text 2",
						"href": null
					}
				]
			},
			{
				"type": "rich_text",
				"rich_text": [
					{
						"type": "text",
						"text": {
							"content": "another text",
							"link": null
						},
						"annotations": {
							"bold": false,
							"italic": false,
							"strikethrough": false,
							"underline": false,
							"code": false,
							"color": "default"
						},
						"plain_text": "another text",
						"href": null
					}
				]
			}
		],
		"function": "show_original"
	}
}

{
	"filter": {
		"property": "rollup property",
		"rollup": {
			"any": {
				"text": {
					"contains": "update text"
				}
			}
		}
	}
}

{
	"filter": {
		"property": "rollup property",
		"rollup": {
			"any": {
				"rich_text": {
					"contains": "update text"
				}
			}
		}
	}
}

"formula property": {
	"id": "m%5D%3F%5C",
	"type": "formula",
	"formula": {
		"type": "string",
		"string": "update text 2,another text"
	}
}

{
	"filter": {
		"property": "formula property",
		"formula": {
			"text": {
				"contains": "update text"
			}
		}
	}
}

{
	"filter": {
		"property": "formula property",
		"formula": {
			"string": {
				"contains": "update text"
			}
		}
	}
}

​

Property list items now have types

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "type": "relation",
      "relation": {
        "id": "83f92c9d-523d-466e-8c1f-9bc2c25a99fe"
      }
    },
 		...
  ],
  "next_cursor": "some-next-cursor-value",
  "has_more": true,
  "rollup": {
    "type": "date",
    "date": {
      "start": "2021-10-07T14:42:00.000+00:00",
      "end": null
    },
    "function": "latest_date"
  },
  "type": "rollup"
}

{
  "object": "list",
  "results": [
    {
      "object": "property_item",
      "id": "xYz890",
      "type": "relation",
      "relation": {
        "id": "83f92c9d-523d-466e-8c1f-9bc2c25a99fe"
      }
    },
 		...
  ],
  "next_cursor": "some-next-cursor-value",
  "has_more": true,
  "type": "property_item",
  "property_item": {
    "id": "aBcD123"
    "next_url": "https://api.notion.com/v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75/properties/aBcD123?start_cursor=some-next-cursor-value",
    "type": "rollup",
    "rollup": {
    	"type": "date",
    	"date": {
      	"start": "2021-10-07T14:42:00.000+00:00",
      	"end": null
    	},
    	"function": "latest_date"
		}
  },

}

​

Deprecated the List Databases endpoint

​

Bug fixes and performance improvements

• We added an optimization for search when filtering by pages or databases. This should particularly help latency when using search to power a database picker in a large workspace. For more details about search and how to optimize search requests, see the search documentation.
• We fixed an issue where fetching an embed block containing an uploaded file returned the wrong file URL.

​

Caption property is now supported for code block type

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block-id",
            "created_time": "2021-10-14T18:10:00.000Z",
            "last_edited_time": "2021-10-14T18:10:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "code",
            "code": {
                "caption": [
                    {
                        "type": "text",
                        "text": {
                            "content": "Hello Caption!",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "Hello Caption!",
                        "href": null
                    }
                ],
                "text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "const foo = \"bar\"",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "const foo = \"bar\"",
                        "href": null
                    }
                ],
                "language": "javascript"
            }
        },
    ],
    "next_cursor": null,
    "has_more": false
}

​

Simple tables and simple table rows

{
	"type": "table",
	"table": {
		"table_width": 3,
		"has_column_header": false,
		"has_row_header": false
	}
}

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

​

Content capabilities

• The read content capability gives the integration access to read existing content in a Notion workspace.
• The insert content capability gives the integration permission to create new content in a Notion workspace.
• The update content capability gives the integration permission to update existing content in a Notion workspace.

​

User capabilities

• No user information - the integration will not be able to request any information about users. User objects will not include information about the user, including name, profile images, or their email address.
• User information without email addresses - user objects will include other information about the user, including their name or profile images, but omit the email address.
• User information with email addresses - user objects will include all information about the user, including name, profile images, and their email address.

​

Limitations

​

Existing integrations

​

Updating integrations

​

Time zone support

​

Synced Block, Link to Page and Template block types are now supported in the API

​

synced_block block type

{
    "type": "synced_block",
    "synced_block": {
        "synced_from": null,
        "children": [
            {
                "callout": {
                    "text": [
                        {
                            "type": "text",
                            "text": {
                                "content": "Callout in synced block"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

{
    "type": "synced_block",
    "synced_block": {
        "synced_from": {
            "block_id": "original_synced_block_id"
        }
    }
}

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block_id",
            "created_time": "2021-11-17T22:17:00.000Z",
            "last_edited_time": "2021-11-17T22:17:00.000Z",
            "has_children": true,
            "archived": false,
            "type": "synced_block",
            "synced_block": {
                "synced_from": {
                    "type": "block_id",
                    "block_id": "original_synced_block_id"
                }
            }
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

link_to_page block type

{
    "children": [
        {
            "type": "link_to_page",
            "link_to_page": {
                "type": "page_id",
                "page_id": "61cca5bd-c8c6-4fcc-b517-514da3b8b1e0"
            }
        }
    ]
}

​

template block type

{
    "children": [
        {
            "type": "template",
            "template": {
                "text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "Create callout template"
                        }
                    }
                ],
                "children": [
                    {
                        "callout": {
                            "text": [
                                {
                                    "type": "text",
                                    "text": {
                                        "content": "Placeholder callout text"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

​

Validation on embed block URLs

• Framer
• Twitter (tweets)
• Google Drive documents
• Gist
• Figma
• Invision,
• Loom
• Typeform
• Codepen
• PDFs
• Google Maps
• Whimisical
• Miro
• Abstract
• Excalidraw
• Sketch
• Replit

​

Dates with times and timezones are now supported on Database Date Filters

{
    "filter": {
        "or": [
            {
                "property": "My Time Property",
                "date": {
                    "before": "2021-10-20"
                }
            }
        ]
    },
    "sorts": []
}

{
    "filter": {
        "or": [
            {
                "property": "My Time Property",
                "date": {
                    "before": "2021-10-15T12:00:00-07:00"
                }
            }
        ]
    },
    "sorts": []
}

​

Breadcrumb block types are now supported in the API

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block-id",
            "created_time": "2021-10-14T18:10:00.000Z",
            "last_edited_time": "2021-10-14T18:10:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "breadcrumb",
            "breadcrumb": {}
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

Table of contents and divider block types are now supported

​

Table of Contents blocks

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block-id",
            "created_time": "2021-10-14T18:10:00.000Z",
            "last_edited_time": "2021-10-14T18:10:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "table_of_contents",
            "table_of_contents": {}
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

Divider blocks

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block-id",
            "created_time": "2021-10-14T18:10:00.000Z",
            "last_edited_time": "2021-10-14T18:10:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "divider",
            "divider": {}
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

Users can now add Equation Blocks, Embed, Bookmark, and Media Blocks

​

Equation Blocks

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "2d97bf53-7e79-4efd-a6b2-53c0026ed1b5",
            "created_time": "2021-10-11T17:56:00.000Z",
            "last_edited_time": "2021-10-11T17:56:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "equation",
            "equation": {
                "expression": "e = mc^2"
            }
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

Media Blocks (video, audio, image, file, pdf)

{
    "object": "block",
    "id": "37af9d6e-290a-488b-9d53-fb4b983f8289",
    "created_time": "2021-10-12T23:11:00.000Z",
    "last_edited_time": "2021-10-12T23:12:00.000Z",
    "has_children": false,
    "archived": false,
    "type": "video",
    "video": {
        "caption": [
            {
                "type": "text",
                "text": {
                    "content": "My caption",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "default"
                },
                "plain_text": "My caption",
                "href": null
            }
        ],
        "type": "external",
        "external": {
            "url": "https://www.youtube.com/watch?v=aA7si7AmPkY"
        }
    }
}

​

Embed and Bookmark Block Types

{
    "object": "block",
    "id": "050010f8-d164-4f5d-85a0-fc9db4598107",
    "created_time": "2021-10-12T23:05:00.000Z",
    "last_edited_time": "2021-10-12T23:06:00.000Z",
    "has_children": false,
    "archived": false,
    "type": "bookmark",
    "bookmark": {
        "caption": [
            {
                "type": "text",
                "text": {
                    "content": "My caption",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "default"
                },
                "plain_text": "My caption",
                "href": null
            }
        ],
        "url": "http://www.notion.so"
    }
}

​

Users can now add and update Callout and Quote block types

​

Quote blocks

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block-id",
            "created_time": "2021-10-07T19:21:00.000Z",
            "last_edited_time": "2021-10-07T19:21:00.000Z",
            "has_children": false,
            "archived": false,
            "type": "quote",
            "quote": {
                "text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "The digital revolution is far more significant than the invention of writing or even of printing.",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": true,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "The digital revolution is far more significant than the invention of writing or even of printing.",
                        "href": null
                    },
                    {
                        "type": "text",
                        "text": {
                            "content": "\n-Douglas Engelbart",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "\n-Douglas Engelbart",
                        "href": null
                    }
                ]
            }
        }
    ],
    "next_cursor": null,
    "has_more": false
}

​

Callout blocks

{
    "object": "block",
    "id": "block-id",
    "created_time": "2021-10-07T19:23:00.000Z",
    "last_edited_time": "2021-10-07T19:24:00.000Z",
    "has_children": false,
    "archived": false,
    "type": "callout",
    "callout": {
        "text": [
            {
                "type": "text",
                "text": {
                    "content": "Note: Something special is happening above",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "default"
                },
                "plain_text": "Note: Something special is happening above",
                "href": null
            }
        ],
        "icon": {
            "type": "emoji",
            "emoji": "💡"
        }
    }
}

​

Retrieve page property item

curl --request GET \
  --url http://localhost:3000/v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75/properties/some-property-id \
  --header 'Authorization: Bearer $NOTION_API_KEY' \
  --header 'Notion-Version: 2021-08-16'

{
  "object": "property_item",
  "type": "number",
  "number": 2
}

{
    "object": "list",
    "results": [
        {
            "object": "property_item",
            "type": "rich_text",
            "rich_text": {
                "type": "text",
                "text": {
                    "content": "Avocado ",
                    "link": null
                },
                "annotations": {
                    "bold": false,
                    "italic": false,
                    "strikethrough": false,
                    "underline": false,
                    "code": false,
                    "color": "default"
                },
                "plain_text": "Avocado ",
                "href": null
            }
        },
... // additional results omitted.
    ],
    "next_cursor": "some-next-cursor-value",
    "has_more": true
}

curl --request GET \
  --url http://localhost:3000/v1/pages/b55c9c91-384d-452b-81db-d1ef79372b75/properties/some-property-id?page_size=10&start_cursor=some-cursor-value \
  --header 'Authorization: Bearer $NOTION_API_KEY' \
  --header 'Notion-Version: 2021-08-16'

{
    "object": "list",
    "results": [
        {
            "object": "property_item",
            "type": "relation",
            "relation": {
                "id": "de5d73e8-3748-40fa-9102-f1290fe2444b"
            }
        },
        {
            "object": "property_item",
            "type": "relation",
            "relation": {
                "id": "164325b0-4c9e-416b-ba9c-037b4c9acdfd"
            }
        },
        {
            "object": "property_item",
            "type": "relation",
            "relation": {
                "id": "456baa98-3239-4c1f-b0ea-bdae945aaf33"
            }
        }
      ...
    ],
    "next_cursor": "some-next-cursor-value",
    "has_more": true,
    "rollup": {
        "type": "date",
        "date": {
            "start": "2021-10-07T14:42:00.000+00:00",
            "end": null
        },
        "function": "latest_date"
    },
    "type": "rollup"
}