"Notion-Version" header will be required starting June 1, 2021

4 months ago by Ankur Oberoi

The Notion API has recommended using an explicit version to every HTTP request, using the Notion-Version header. For integrations created after June 1, 2021 an explicit version on every request will become required. After July 1, 2021, integrations created before June 1, 2021 will also have the same requirement. Today, the most recent version is "2021-05-13".

Is my integration affected? What should I do to update?

This requirement will not break your existing integration; however, we will start enforcing this requirement for all API requests on July 1st. Starting July 1st, if you don't send the Notion-Version header with your Notion API calls, you will get a "missing_version" error. Learn more about how the Notion API handles versioning.

If you've been using examples copied from documentation or example code since the public beta, including using the Notion SDK for JavaScript, your existing code should continue to work as expected.

Otherwise, please make one of the two following changes before July 1:

  1. Add Notion-Version: 2021-05-11 in the header when making requests (no other code change is needed).
  2. Recommended: Add Notion-Version: 2021-05-13 in the header when making requests. Making this change will move you to our newest version which includes the following breaking change.

Breaking changes in version 2021-05-13

The type of property value objects for rich text properties has changed from "text" to "rich_text".

When creating pages and updating page properties, update page property values that are rich text to use the key rich_text instead of text. Similarly when retrieving a page, rich text properties will be returned with the type "rich_text" instead of "text".

This change helps distinguish between the property type, and the inner text values of rich text object, which have the key text.

To illustrate this change, here is an example of how the page object's properties appear before and after:

// Before (in unversioned requests and responses)
{
  "object": "page",
  "properties": {
    "Description": {
      "type": "text",
      "text": [
        {
          "type": "text",
          "text": { "content": "Hello World" }
        }
      ]
    }
  }
  /* remaining details omitted */
}
// After (in requests and responses with version 2021-05-13)
{
  "object": "page",
  "properties": {
    "Description": {
      "type": "rich_text",
      "rich_text": [
        {
          "type": "text",
          "text": { "content": "Hello World" }
        }
      ]
    }
  }
  /* remaining details omitted */
}