Using the Notion API
Notion integrations let you connect your workspace to external tools and automate workflows through code. With the REST API, you can read, create, and update nearly everything in a workspace — pages, databases, users, comments, and more. When you create an integration, you define what it can do: which API endpoints it can call, what content it can read or write, and how it authenticates. Each integration gets its own credentials and its own set of permissions.What is a Notion integration?
A Notion integration — sometimes called a connection — connects your workspace to external apps and tools. That could be a SaaS product, an automation script, or a custom tool you’ve built. Integrations are added to Notion workspaces and require explicit permission from users to access Notion pages and databases.
Integration types
Notion integrations come in two types:- Internal integrations are scoped to a single workspace and use a static API token. They’re ideal for custom automations and workflows — things like syncing data, sending notifications, or building internal dashboards.
- Public integrations use OAuth 2.0 for authentication. At creation time, you choose their installation scope: Any workspace (any Notion user can install; Marketplace-eligible) or Selected workspaces only (restricted to workspaces you approve; not Marketplace-eligible).
Public integrations must undergo a Notion security review before being listed on the Marketplace. You can create and use a public integration without listing it.
Comparison
| Feature | Internal integrations | Public integrations |
|---|---|---|
| Installation scope | Single workspace. | Any workspace, or a specific set of workspaces chosen at creation time. Scope can’t change after creation. |
| User access | Only members of the workspace where it’s installed. | Any user in a workspace where the integration is allowed to install. |
| Content access | Granted directly to the integration, not tied to any specific user. | Users choose which pages to share during the OAuth flow or via the Add connections menu. |
| Authentication | Static API token. | OAuth 2.0. |
Looking for SCIM or SAML SSO?Enterprise identity management (user provisioning, group management, and Single Sign-On) is covered in Notion’s Help Center, not in these API docs.
Provision users and groups with SCIM
SAML SSO configuration
Shared concepts
All integration types share a few core concepts.Capabilities
Every integration has a set of capabilities that control what it can do — read content, update content, insert content, read comments, and more. You configure capabilities when you create an integration, and you can update them later. See the Capabilities reference for the full list.Pages
Create, update, and retrieve page content.
Databases
Manage database, properties, entries, and schemas.
Views
Create and configure database views programmatically.
Data sources
Manage data sources, properties, entries, and schemas.
File uploads
Upload and attach files to pages and databases.
Comments
Handle page and inline comments.
Content queries
Search through workspace content.
Users
Access user profiles and permissions.
Content access
Integrations must be explicitly granted access to pages and databases before they can interact with them. The mechanism differs by type:- Internal integrations can be granted access in two ways: the integration owner can add pages directly from the Content access tab in the Creator dashboard, or workspace members can share pages via the Add connections menu in Notion.
- Public integrations use the OAuth page picker, where users select which pages to grant access to during the authorization flow.
Webhooks
Integrations can subscribe to real-time events — like page updates, property changes, and new comments — via webhooks. This allows your integration to react to changes in Notion without polling the API. See the Webhooks guide for details on setting up webhook subscriptions.Starting your integration journey
We recommend starting with an internal integration — it’s the fastest way to begin building. You get an API token immediately and can focus entirely on using the API within your workspace, without worrying about OAuth or Marketplace listing. You can always create a public integration later if you need multi-workspace support. Here’s a guided path through the documentation:Quickstart — Build your first integration with a hands-on tutorial.
Internal integrations — Understand how internal integrations work, including the permissions model.
Public integrations — Learn how public integrations work, including installation scope and the OAuth flow.
Authorization — Implement the OAuth 2.0 flow for public integrations.
Handling API keys — Secure and manage your API tokens in production.
Preparing for users — Set up databases, pages, and views automatically when users install your integration.
List on the Marketplace — Make your public integration discoverable to all Notion users.