Versioning

The Notion API is versioned. Our API versions are named for the date the version is released, for example, our latest version is 2022-06-28.

You set the version by including a Notion-Version header.

cURLJavaScript

curl https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5 \
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

A new API version is released when we introduce a backwards-incompatible change to the API. For example, changing a property type's name.

JSON

// Prior to version 2021-05-13, the rich text property is called "text"
"properties": {
    "Description": {
    "type": "text"
        "text": [ ... ]
    }
}

// In version 2021-05-13, the rich text property is now called "rich_text"
"properties": {
    "Description": {
    "type": "rich_text"
        "rich_text": [ ... ]
    }
}

In the above example, if you do not upgrade to the new version, you will continue to set text properties using text when creating or updating a page. Once you upgrade to the new version, you will need to use rich_text to set that same text property.

Similarly, the page response will be returned with the property type text on the old version, while on the new version, the response will say rich_text.

🚧Required Header

We strongly encourage you to include the Notion-Version header for all requests. This best ensures the Notion API is consistent with what your code expects. We will be requiring that all API calls include the Notion-Version header starting June 1, 2021.

📘Versioning is only for backwards incompatible changes

For new features and additions to the API, such as adding a new API endpoint, or including a new object in an existing API endpoint's response, there won't be a new version. You'll be able to take advantage of any new functionality on the version of the API you're currently using.

Note: You may have noticed that Notion API URLs contain a v1. This is not related to the versioning described above. We don't intend to change these URLs.