Releasing Notion-Version 2022-06-28

Update from August 31, 2022: Page properties can now be retrieved using the page, query database, and search endpoints, in addition to the page properties endpoint.

Today we’re releasing Notion-Version 2022-06-28 with the following backwards incompatible changes:

• 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.

Read more about each of these changes below.

Page properties must be retrieved using the page properties endpoint

Previously, the page object returned from page endpoints, as well as the query database and search endpoint, returned a properties field that contained all the page’s properties along with its value:

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

While convenient, returning accurate results for all properties resulted in bad performance and timeouts for larger databases or pages with lots of mentions. To combat performance, on March 1st, we added a disclaimer that page objects stopped returning accurate results for pages with more than 25 mentions to other objects (which affected properties of type title, rich_text, relation, people, rollup, and formula).

In October 2021, we introduced a way to more accurately retrieve individual page properties via the retrieve a page property item endpoint. With this endpoint, we’re able to paginate complex properties that involve additional look-ups.

With version 2022-06-28, the type and property value from page objects are removed. Thus moving forward, all property value retrieval must happen through the retrieve a page property item endpoint.

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

For more examples of how to use the retrieve a page property item endpoint, our SDK examples have been updated to use the retrieve a page property item endpoint.

For more details about why page properties are so complex, we wrote about it in our “Creating the Notion API” blog post.

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

Previously, when accessing the parent of a database or page, that parent was always either a page, database, or workspace. This is un-faithful to the actual data model of Notion, where the parent may also be another block; for example, you can nest a page under a toggle block.

The parent field for page and database has been changed so that it is now always the direct parent of that page or database, and a new parent type has been added: block_id.

Additionally, a parent field has been added to the block object. Together, these changes allow you to fully traverse Notion’s tree.

To emulate the previous behavior of retrieving the page, database, or space parent, you may traverse up the tree using the retrieve a block endpoint. If the parent ≠ one of those types, retrieve the parent block until it is.

Read more about parent types here.

Database relations have a type of single_property and dual_property

Relation properties in databases objects now have a type of single_property or dual_property. These can be used to create one way relations between databases as well as two way relations within a database.

New version of the JavaScript SDK

Coinciding with all of these changes, we've released a new major version (v2.0.0) of the Notion JavaScript SDK. To upgrade to this new version, run npm install @notionhq/client@latest or yarn upgrade --latest @notionhq/client from within your repository.