Official vs Internal API

Did you know there’s 2 different Notion APIs in use? Learn about the pros and cons here.

If you’re getting started with Notion development, you may find yourself confused looking at different examples, until you realize that there are 2 different Notion APIs in use - the official API documented at https://developers.notion.com/, and the internal API used by Notion itself.

These two APIs are both REST APIs that return JSON responses, but that’s about it for the similarities.

API Comparison #

Official API #

  • Officially documented and supported APIs for developers at https://developers.notion.com/
  • URLs start with https://api.notion.com/v1/
  • Released as a public beta in May 2021 and out of beta as of on March 2, 2022.
  • Allows for more secure sharing of individual pages
  • Admin user must install into the workspace using OAuth permissions, then pages and databases must be shared with the integration by users, whether or not they are public
  • More wordy JSON responses, particularly around text formatting
  • Not all Notion functionality is supported
  • Breaking changes are introduced through versioning the API; while older versions may eventually stop working, there should be plenty of warning

Internal API #

  • The API calls that Notion itself uses
  • URLs start with https://www.notion.so/api/v3/
  • Older - integrations built pre-2021 use this or web scraping
  • Can access Public pages easily; accessing private pages requires using user tokens granting full access, which could let a malicious app do anything with your Notion account
  • Undocumented, but some client libraries exist
  • More concise but harder to understand JSON responses
  • Higher risk of unannounced breaking changes as this is an internal API

So which API should you use? #

If your app can make use of the official API, that is likely the safest choice for longer term compatibility and support. However, the official API is still actively being built out and some important functionality like working with views is not currently possible, and the unofficial API is convenient for apps using Public pages as they can retrieve information easily with less hassle than setting up OAuth. There is considerable platform risk to working with the unofficial API as Notion could change it at any time with little notice, and so I would suggest a strong bias towards the official API for new development in 2022 and beyond, but some scenarios just aren’t possible on it yet.