Notion API Basics
The Notion API lets other software communicate with your Notion workspace. Developers use it to read, create, and update pages programmatically. This topic covers the core concepts without requiring you to write code.
What the API Enables
An API acts as a bridge between two systems. It lets an outside app pull data from Notion or push new data into it. This connection powers integrations like syncing a form submission into a database.
API as a Bridge
| External App | Bridge | Notion Workspace |
|---|---|---|
| Form tool, calendar app, script | Notion API | Pages and databases |
Creating an Integration
Visit the Notion integrations page in your account settings to create a new integration. Notion generates a secret key called an API token for this integration. This token acts like a password that grants the integration access, so store it privately and never share it in public code.
Connecting a Database to an Integration
Open the database you want to expose to the API. Click the three dots menu and find Connections. Add your integration from this list to grant it access to that specific database.
Access Without Connection
| State | API Access |
|---|---|
| Integration not connected to database | No access, request fails |
| Integration connected to database | Full access based on integration permissions |
Common API Actions
- Retrieve entries from a database
- Create a new page inside a database
- Update a property on an existing entry
- Search across pages in a workspace
Internal vs Public Integrations
An internal integration connects only to your own workspace and suits personal or company-specific tools. A public integration can connect to many different workspaces after each owner approves it, similar to installing an app from a marketplace. Most beginners only ever need an internal integration.
Internal vs Public Integration
| Type | Works Across Workspaces | Typical Use |
|---|---|---|
| Internal | No, one workspace only | Personal scripts, company tools |
| Public | Yes, with owner approval | Third-party apps and services |
Third-Party Integration Tools
Automation platforms let non-developers connect Notion to other apps without writing code. These tools offer prebuilt connections, such as adding a new database row when a form is submitted. This approach suits users who want API power without programming skills.
When to Use the API
Use the API when built-in Notion Automations cannot handle a task. Common cases include syncing data from an external tool or building a custom app on top of Notion. Beginners can rely on third-party automation tools before writing direct API calls.