Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Is my connection affected? What should I do to update?

This requirement will not break your existing connection; 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:
JavaScript
// Before (in unversioned requests and responses)
{
  "object": "page",
  "properties": {
    "Description": {
      "type": "text",
      "text": [
        {
          "type": "text",
          "text": { "content": "Hello World" }
        }
      ]
    }
  }
  /* remaining details omitted */
}
JavaScript
// 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 */
}