Introduction to Notion’s API
Learn about Notion’s public API and building integrations.
Using Notion’s public API to build integrations
Developers can use Notion’s public REST API to interact with Notion workspaces programmatically. Interactions include working with:
- Pages
- Databases
- Users
- Page and inline comments
- Querying workspace content
- Authenticating integrations
- Customizing unfurled links
All workspace interactions, such as the above, need to be attributed to a Notion user. To accommodate this requirement for interactions made programmatically, Notion allows for API requests to be attributed to a "bot". To define the capabilities of a bot, developers build integrations, which handle authenticating API requests for the bot, defining when requests should be made, and the read/write capabilities of the integration.
In other words, using Notion’s public API means building an integration — the blueprint for how a bot can interact with your workspace — and attributing the REST API requests that are made to the bot.
There are two main types of integrations:
- Internal
- Public, which include Link Previews
Keep reading to learn more about types of integrations and some example ideas of what developers can build. Alternatively, jump to the API reference documentation to learn more about available endpoints, or see our collection of integration demos for sample code.
What is a Notion integration?
A Notion integration (sometimes referred to as a "connection") allows developers to interact with Notion workspaces programmatically. This allows developers to connect their Notion workspace data to other tools or automate workflows within Notion.
Integrations are installed in Notion workspaces and require explicit permission from users to access Notion pages and databases.
You can build Notion integrations that help collaborators expand what they can do with Notion
There is a large library of existing integrations available to Notion users to improve their Notion experiences. For developers looking to build their own integration, they can create either public or internal integrations, both of which rely on the REST API to interact with workspaces.
Let’s look deeper at what these two types of integrations are and how they differ.
Internal vs. public integrations
Internal integrations
An internal integration is tied to a single, specific workspace. Only members within the workspace can use the integration. They are created by Workspace Owners through the integration dashboard.
By default, all integrations start out as internal integrations.
You can set an integration to public from the integration’s settings page.
Once an internal integration has been added to a workspace, members must give the integration permission to access specific pages or databases through Notion’s UI.
In order to add an internal integration to the workspace, a Notion member needs to be a Workspace Owner. If you don’t have admin access to the target workspace, then you can always develop the integration in a personal workspace, and later ask a Workspace Owner for assistance.
Workspace Owners can see all integrations created in the integration dashboard — both ones they and others have created.
To learn more about internal integrations, read our Create an integration and Authorization guides.
Public integrations
Public integrations are built for a broad audience. Any Notion user in any workspace can use a public integration. This is in contrast to internal integrations, which are built for a specific workspace.
By default, all integrations start out as internal integrations and can be made public via the integration’s settings page.
Public integrations follow the OAuth 2.0 protocol to access multiple workspaces. To share pages with public integrations, users either select pages from the page picker interface during the authorization flow, or they can share individual pages from the workspace.
This is explained in more detail in our Authorization guide.
Add a template to an integration
When you create a public integration, you can provide a URL to a Notion page that a user can opt to duplicate in their workspace during the OAuth flow.
Learn more about using templates in the Authorization guide.
What you can build: Integration use cases
"Integrations" is a broad term in terms of what can be built with Notion’s REST API. Let’s look at some examples of different types of internal and public integrations that have been built with Notion.
For code examples, see the Notion SDK for JavaScript's examples directory.
Data integrations
You can use the Notion API to build an integration that sends data to and/or from Notion. For example, you can poll for changes to a Notion database to send automated emails, sync Notion with Github issues, or import data from an external source to a Notion database.
Related resources
Link Preview integrations
Link Preview integrations are a type of public integration that handle how links unfurl. With a Link Preview integration, you can share an excerpt of content in Notion when an authenticated collaborator shares a supported link.
Link Preview of a GitHub PR
In other words, developers can build Link Preview integrations to allow links with a domain they own to unfurl in a customizable format. Since Link Preview integrations use OAuth 2.0, the main benefit of Link Preview integrations is being able to display information that requires users to be authenticated to view.
Note: Authorizing Link Preview integrations differs from other public integrations. Use the Link Preview guide to set up authorization.
Related resources
To build a Link Preview integration, developers must first apply for access to the feature through the Notion Link Preview API request form.
Additionally, all Link Preview integrations published for distribution require a review from Notion's platform and security teams.
Identity management integrations
Workspaces on Notion’s enterprise plan are granted access to a SCIM API. SSO using SAML can also be configured for enterprise workspaces.
Related resources
These examples represent just a few ideas. Join our Notion Devs Slack community to share your own ideas, and learn from other developers building with Notion.
Getting started
If you’re new to Notion’s public REST API and integrations, we recommend starting with the:
- Create an integration guide
Once you have a good idea of how to create an integration, continue learning with the following guides:
See our API reference docs for a list of available endpoints, a more in-depth description of each type of object used in Notion, and ensuring your integrations have the correct capabilities.
Notion SDK for JavaScript
Notion has built an SDK for integrations built in a JavaScript environment to simplify interacting the with REST API. We typically recommend JavaScript developers use this SDK.
Key resources
Technology Partner Program
If you’ve already built a public integration using our Public API or the Link Previews API, you may be eligible to become a technology partner and receive dedicated support from Notion, as well as access to exclusive distribution and marketing opportunities.
See our Technology Partner Program page to learn more.
Updated 4 months ago