Notion API

Set up API access for reading and writing Notion pages, databases, and blocks.

⏱ 5 minutes productivity notes www.notion.so

getapi notion

Prerequisites

A Notion account
A Notion workspace where you have owner access

Credentials

Variable	Description	Sensitive
`NOTION_API_KEY`	Internal integration token (starts with ntn_ or secret_)	Secret

Setup Steps

1 Info

We'll create a Notion internal integration and get an API token. You'll also need to share specific pages or databases with the integration before it can access them.
2 Open URL

Opening the Notion integrations page. Sign in if prompted.
https://www.notion.so/profile/integrations/internal
3 Choice
Do you already have an integration you want to use?
- Create a new integration
  
  → Jumps to create_integration
- Use an existing integration
  
  → Jumps to select_existing
4 Info

Click 'New integration'. Give it a name, select the workspace it belongs to, and choose its capabilities (Read content, Update content, Insert content). For full access, enable all content capabilities.
5 Confirm

Integration created?

Checkpoint — confirm before continuing
6 Info

Click on your existing integration to view its settings.
7 Input

Under 'Internal Integration Secret' in the Configuration tab, click 'Show' and copy the token. Paste it here:

→ NOTION_API_KEY

At least 20 characters
8 Info

Important: The integration can only access pages and databases that have been explicitly shared with it. Go to any Notion page or database, click the '...' menu in the top right, select 'Connections', and add your integration.
9 Confirm

Shared at least one page or database with your integration?

Checkpoint — confirm before continuing
10 Validate

Checking your integration token works...

Integration token verified. Notion API is ready.

Couldn't verify the token. Make sure you copied it correctly and the integration is active.

Things to Know

Integrations can ONLY access pages and databases explicitly shared with them. This is the most common source of 'not found' errors.
When you share a parent page, all child pages are also accessible. You don't need to share each one individually.
Notion API has a rate limit of 3 requests per second. Implement retry logic with exponential backoff.
The Notion API requires a 'Notion-Version' header (e.g., '2022-06-28'). Most Notion client libraries handle this automatically.
Internal integration tokens do not expire, but they can be revoked from the integrations page.
If using the API directly (not a client library), you must include both 'Authorization: Bearer <token>' and 'Notion-Version: 2022-06-28' headers.