A Notion API key is the token your code sends to the Notion API. Create an internal connection in Notion's Developer portal and copy its API token from the Configuration tab, then share each page with the connection. Every request needs that token as a Bearer value plus a Notion-Version header.
| Item | Value |
|---|---|
| Base URL | https://api.notion.com/v1 |
| Auth header | Authorization: Bearer <token> |
| Notion-Version (latest) | 2026-03-11, required on every request |
| Rate limit, most plans | 180 requests per minute, an average of 3 per second |
| Rate limit, Business and Enterprise | 600 requests per minute, an average of 10 per second |
| Over the limit | HTTP 429 with code rate_limited and a Retry-After in seconds |
Updated
Hooking Notion up to your site, a form or an agent starts with one token. Notion has two ways to get it: an internal connection, which only sees pages you share with it, and a personal access token, which acts as you. Paste a page link below and this page builds a ready-to-run request for it, with the token kept as a placeholder.
Paste a Notion page link or ID and choose what to do. The request uses $NOTION_API_KEY, so set that variable in your terminal first. Nothing leaves your browser.
Page ID: 01234567-89ab-cdef-0123-456789abcdef
curl https://api.notion.com/v1/pages/01234567-89ab-cdef-0123-456789abcdef \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2026-03-11"Set the token once in your terminal, then call the search endpoint. With no query it returns every page shared with the connection.
Replace the placeholder with your real token only in your own terminal, never in a file you commit.
export NOTION_API_KEY="ntn_your_token_here"
curl -X POST https://api.notion.com/v1/search \
-H "Authorization: Bearer $NOTION_API_KEY" \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
-d '{"filter":{"property":"object","value":"page"}}'Plain fetch from a server or serverless function, with a simple wait on 429.
export async function notion(path, init = {}) {
const res = await fetch(`https://api.notion.com/v1/${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.NOTION_API_KEY}`,
"Notion-Version": "2026-03-11",
"Content-Type": "application/json",
...init.headers,
},
});
if (res.status === 429) {
const wait = Number(res.headers.get("Retry-After") || 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return notion(path, init);
}
if (!res.ok) throw new Error(`Notion ${res.status}: ${await res.text()}`);
return res.json();
}The page ID is the 32 hexadecimal characters at the end of a Notion page link, after the title. The builder below finds it in a pasted link and writes it in the dashed UUID form the API returns.
Anyone holding the token can do whatever the connection is allowed to do on the shared pages. Keep the token in your host's secret settings, and create a fresh one if it is ever pasted somewhere public.
For an internal connection, open it in the Developer portal and look under the Configuration tab for the API token. A personal access token is shown once when you create it, so copy it straight away.
An internal connection is tied to one workspace and only reaches pages shared with it, which suits a site or automation. A personal access token authenticates as you. Public connections use OAuth instead, for apps other workspaces install.
Notion requires each page to be manually shared with the connection before it can read or write it. Use Add connections from the page's ••• menu, then try again.
As of October 2026, Notion lists 180 requests per minute (about 3 per second) on most plans and 600 per minute on Business and Enterprise. Extra requests get HTTP 429 with the rate_limited code.
Notion's versioning page names 2026-03-11 as the most recent version. The header is required on all REST API requests; the official SDK sets it for you.
Related: What is an API key?, How to build an AI agent, .env file format, Rate limiting explained, Notion Sites compared.
Start for free or see all free tools. We.Inc is free to start, with no card needed. AI building is on paid plans from $20 a month.
We.Inc is an AI-powered website builder you can resell under your own brand. Launch a branded client dashboard, bill on Stripe Connect, and deliver AI-generated websites in minutes. White-label plans start at $99 a month for 25 client sites, with a 7-day free trial and no per-site fees.