Skip to main content
The Notion API is versioned. Our API versions are named for the date the version is released. For example, our latest version is . Set the version by including a Notion-Version header. Setting this header is required. 
curl https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5 \
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2025-09-03"
A new API version is released when we introduce a backwards-incompatible change to the API. For example, changing a property type’s name. 
// 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 HeaderThe Notion-Version header must be included in all REST API requests. This ensures the Notion API response is consistent with what your code expects.The most recent Notion-Version is .
Versioning is only for backwards incompatible changesFor 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 notice that Notion API URLs contain a v1. This is not related to the versioning described above. We don’t intend to change these URLs.

​
Frequently asked questions

Releases of the Notion SDK for JavaScript are published to NPM as @notionhq/client and use a separate semantic versioning scheme. View the GitHub release notes for the latest version and changes over time. Some SDK changes are also featured in the API changelog.When upgrading to a new “minor” or “patch” version of the SDK, you generally won’t need to make any code changes to your integration. These updates contain backwards-compatible improvements and fixes.However, new “major” versions of the SDK are not backwards-compatible, and you may need to make updates to your integration.
Some major releases drop support for older Notion API versions and update the default version used to make requests when no notionVersion is provided to the SDK Client constructor.

For example, v5.0.0 and above dropped support for 2022-06-28 and earlier, and only works well with 2025-09-03 and above.

To manage this upgrade, refer to the upgrade guide. See the compatibility table in the README to see which versions of the SDK are compatible with which versions of the API.
We don’t currently have any plans to stop supporting older API versions. If this changes in the future, we’ll communicate this with all affected users and provide a time window and migration guidance. However, we recommend upgrading to the latest version to take advantage of the latest features and improvements.