[metadata]
apple-mobile-web-app-title: Notion Docs
application-name: Notion Docs
description: Discover what Notion connections are, when to use each type, and what you can build.
generator: Mintlify
msapplication-TileColor: #000
msapplication-config: /mintlify-assets/_mintlify/favicons/notion-demo/1PaJq9z3waub4TpE/_generated/favicon/browserconfig.xml
og:description: Discover what Notion connections are, when to use each type, and what you can build.
og:image: https://notion-demo.mintlify.app/images/og-image.png
og:image:height: 630
og:image:width: 1200
og:site_name: Notion Docs
og:title: Overview - Notion Docs
og:type: website
og:url: https://developers.notion.com/guides/get-started/overview
twitter:card: summary_large_image
twitter:description: Discover what Notion connections are, when to use each type, and what you can build.
twitter:image: https://notion-demo.mintlify.app/images/og-image.png
twitter:image:height: 630
twitter:image:width: 1200
twitter:title: Overview - Notion Docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://developers.notion.com/guides/get-started/overview

[document-links]
/llms.txt: /llms.txt
API Reference: /reference/intro
API quickstart Next: /guides/get-started/quick-start
API token security: /guides/get-started/handling-api-keys
Admin API: /reference/admin/intro
Authorization: /guides/get-started/authorization
CLI Reference: /cli/get-started/overview
Capabilities reference: /reference/capabilities
Changelog: /page/changelog
Developer portal: https://www.notion.so/developers
Example code: https://developers.notion.com/page/examples
Examples: /page/examples
Guides: /guides/get-started/overview
Handling API keys: /guides/get-started/handling-api-keys
Historical changelog: /guides/resources/historical-changelog
Internal connections: /guides/get-started/internal-connections
Introduction: /guides/link-previews/introduction
List on the Marketplace: /guides/get-started/marketplace-listing
Log in: https://www.notion.com/login
Notion Devs Slack community: https://join.slack.com/t/notiondevs/shared_invite/zt-3u9oid9q8-HLUBmMVWYK~g9HFo4U4raA
Notion Docs home page: /
Overview: /compliance/overview
Overview: /guides/get-started/overview
Personal access tokens: /guides/get-started/personal-access-tokens
Postman workspace: https://www.postman.com/notionhq/notion-s-api-workspace/collection/52041987-03f70d8f-b6e5-4306-805c-f95f7cdf05b9
Preparing for users: /guides/get-started/preparing-for-users
Public connections: /guides/get-started/public-connections
Quickstart: /guides/get-started/quick-start
Webhooks guide: /reference/webhooks
Workers: /workers/get-started/overview
Working with comments: /guides/data-apis/working-with-comments
Working with page content: /guides/data-apis/working-with-page-content
Working with views: /guides/data-apis/working-with-views
connection: https://www.notion.com/help/add-and-manage-connections-with-the-api
installation scope: /guides/get-started/public-connections#installation-scope
library: https://www.notion.com/integrations/all
listed on the Marketplace: /guides/get-started/marketplace-listing
slack: https://join.slack.com/t/notiondevs/shared_invite/zt-3u9oid9q8-HLUBmMVWYK~g9HFo4U4raA
x: https://x.com/NotionDevs

[structured-data]
{"@context":"https://schema.org","@graph":[{"@id":"https://developers.notion.com/#organization","@type":"Organization","logo":{"@type":"ImageObject","url":"https://mintcdn.com/notion-demo/5YdhSbldE14t5Rna/logo/light.svg?fit=max&auto=format&n=5YdhSbldE14t5Rna&q=85&s=249f5693ad929397409bf9b51d6d539d"},"name":"Notion Docs","url":"https://developers.notion.com"},{"@id":"https://developers.notion.com#website","@type":"WebSite","name":"Notion Docs","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com"},{"@id":"https://developers.notion.com/guides/get-started/overview#webpage","@type":"WebPage","breadcrumb":{"@id":"https://developers.notion.com/guides/get-started/overview#breadcrumb"},"dateModified":"2026-07-17T01:15:49.461Z","description":"Discover what Notion connections are, when to use each type, and what you can build.","isPartOf":{"@id":"https://developers.notion.com#website"},"name":"Overview","url":"https://developers.notion.com/guides/get-started/overview"},{"@id":"https://developers.notion.com/guides/get-started/overview#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://developers.notion.com","name":"Notion Docs","position":1},{"@type":"ListItem","item":"https://developers.notion.com/guides/get-started/overview","name":"Overview","position":2}]},{"@id":"https://developers.notion.com/guides/get-started/overview#article","@type":["Article","TechArticle"],"dateModified":"2026-07-17T01:15:49.461Z","description":"Discover what Notion connections are, when to use each type, and what you can build.","headline":"Overview","image":"https://developers.notion.com/images/og-image.png","isPartOf":{"@id":"https://developers.notion.com#website"},"mainEntityOfPage":{"@id":"https://developers.notion.com/guides/get-started/overview#webpage"},"name":"Overview","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com/guides/get-started/overview"}]}

[content]
Overview - Notion Docs
Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Notion Docs
home page
Search...
⌘
K
Ask Assistant
Log in
Developer portal
Developer portal
Search...
Navigation
Get started
Overview
Guides
API Reference
CLI Reference
Workers
Admin API
Changelog
Examples
Get started
Overview
Quickstart
Personal access tokens
Internal connections
Public connections
Authorization
API token security
Preparing for users
List on the Marketplace
Agent APIs
Notion MCP
API versions
Upgrading to 2026-03-11
Upgrading to 2025-09-03
Data APIs
Working with page content
Working with databases
Working with views
Working with comments
Working with markdown content
Working with files and media
Resources
Example code
Postman workspace
Historical changelog
Compliance
Overview
Event reference
Link previews
Introduction
On this page
Using Notion API
What is a Notion connection?
Connection types
Comparison
Shared concepts
Capabilities
Content access
Webhooks
Getting started
Resources
Get started
Overview
Copy page
Copy page
Discover what Notion connections are, when to use each type, and what you can build.
Copy page
Copy page
​
Using Notion API
Notion connections 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 a connection, you define what it can do: which API endpoints it can call, what content it can read or write, and how it authenticates. Each connection gets its own credentials and its own set of permissions.
​
What is a Notion connection?
A Notion
connection
— sometimes called an integration — connects your workspace to external apps and tools. That could be a SaaS product, an automation script, or a custom tool you’ve built.
Connections are added to Notion workspaces and require
explicit permission
from users to access Notion pages and databases.
Create Notion connections that unlock new possibilities for teams.
Notion already has a
library
of connections you can browse. For developers who want to build their own, Notion supports internal connections, public connections, and personal access tokens — all powered by the same REST API.
​
Connection types
Notion supports three authentication models:
Internal connections
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 connections
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 select; not Marketplace-eligible).
Personal access tokens (PATs)
are user-scoped tokens for scripts, CLI workflows, Workers, and tools that should act as one Notion user. A PAT uses the creator’s workspace membership and page permissions. See
Personal access tokens
.
Public connections must undergo a Notion security review before being
listed on the Marketplace
. You can create and use a public connection without listing it.
​
Comparison
Feature
Internal connections
Public connections
Personal access tokens
Best for
Team-owned automations in one workspace.
Apps or services used by many Notion users or workspaces.
User-owned scripts, CLI workflows, Workers, and trusted tools.
Installation scope
Single workspace.
Any workspace, or a specific set of workspaces chosen at creation time. Scope can’t change after creation.
One user in one workspace.
User access
Only members of the workspace where it’s installed.
Any user in a workspace where the connection is allowed to install.
The member who created the token.
Content access
Granted directly to the connection, not tied to any specific user.
Users choose which pages to share during the OAuth flow or via the Add connections menu.
Uses the creator’s Notion permissions; pages do not need to be shared with a bot.
Authentication
Static API token.
OAuth 2.0.
Static bearer token.
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 connection and token types share a few core concepts.
​
Capabilities
Every connection or token 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 a connection or PAT. 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
Connections must have access to pages and databases before they can interact with them. The mechanism differs by type:
Internal connections
can be granted access in two ways: the connection owner can add pages directly from the
Content access
tab in the Developer portal, or workspace members can share pages via the
Add connections
menu in Notion.
Public connections
use the OAuth page picker, where users select which pages to grant access to during the authorization flow.
Personal access tokens
use the token creator’s existing Notion permissions. If the creator can access a page in Notion, a PAT with the right capabilities can access it through the API.
See the
Internal connections
,
Public connections
, and
Personal access tokens
guides for specifics on how content access works for each type.
​
Webhooks
Connections can subscribe to real-time events — like page updates, property changes, and new comments — via webhooks. This allows your connection to react to changes in Notion without polling the API. See the
Webhooks guide
for details on setting up webhook subscriptions.
​
Getting started
The fastest way to start building is the
Quickstart
— create a personal access token, make your first API request, and see a new page appear in your workspace in under two minutes.
Once you’re ready to build further, choose the authentication model that fits your use case:
1
Personal access tokens
— Authenticate as yourself for scripts, CLI workflows, Workers, or trusted tools.
2
Internal connections
— Build team-owned automations with a dedicated bot identity scoped to one workspace.
3
Public connections
— Build apps for other Notion users with OAuth 2.0.
4
Authorization
— Implement the OAuth 2.0 flow for public connections.
5
Handling API keys
— Secure and manage your API tokens in production.
6
Preparing for users
— Set up databases, pages, and views automatically when users install your connection.
7
List on the Marketplace
— Make your public connection discoverable to all Notion users.
​
Resources
Explore the links below to get started, and join the
Notion Devs Slack community
to share your projects and connect with fellow developers.
API reference
Notion SDK for JavaScript
Starter templates
Postman collection
FAQs
Notion Devs Slack
API quickstart
Next
⌘
I
x
slack
Assistant
Responses are generated using AI and may contain mistakes.
