About Notion Developer Platform
If you've ever tried to build a real integration on top of a product's API only to discover it's bolted on as an afterthought — underdocumented, weirdly scoped, and impossible to reason about — you'll appreciate what Notion's Developer Platform is trying to do. The platform gives you a proper REST API with three distinct authentication models, explicit capability controls, and a clear path from a quick personal script all the way to a Marketplace-listed OAuth app. It's not just a webhook endpoint with a logo on it.
The core concept is the "Notion connection" — what some platforms call an integration. You define what a connection can read or write (pages, databases, comments, users), how it authenticates, and which workspaces it can touch. Internal connections use a static API token and stay scoped to one workspace, making them the right call for team automations and internal dashboards. Public connections use OAuth 2.0 and can be installed across any workspace, which is the path if you're building something for other Notion users to install. Personal access tokens (PATs) sit in the middle — user-scoped, static tokens suited for CLI workflows, scripts, and the new Workers runtime.
The platform also ships an MCP (Model Context Protocol) server and "Agent APIs," which signals that Notion is actively thinking about AI-native tooling, not just traditional integrations. There's a Marketplace for public connections, a Postman workspace for exploration, and a CLI reference for the Workers runtime. The documentation index is even published at a machine-readable `/llms.txt` endpoint — a small but telling detail about who this platform is being built for.
Key features
Three authentication models
Notion supports internal connections (static API token, single workspace), public connections (OAuth 2.0, any or selected workspaces), and personal access tokens (user-scoped static bearer tokens), so you pick the auth model that actually fits your use case instead of forcing everything through OAuth.
Granular capability controls
Every connection or PAT has an explicit set of capabilities — read content, update content, insert content, read comments, and more — that you configure at creation time, giving you fine-grained control over what any given integration can actually do.
Full REST API coverage
The API lets you read, create, and update pages, databases, database schemas and properties, views, comments, files, and media — covering nearly everything in a Notion workspace, not just a subset.
Notion MCP and Agent APIs
Notion ships a native MCP (Model Context Protocol) server and dedicated Agent APIs, which means you can wire AI agents directly into Notion's data layer without building a custom middleware layer yourself.
Marketplace distribution for public connections
If you build a public connection and pass Notion's security review, you can list it on the Notion Marketplace, giving your integration direct distribution to Notion's user base without managing your own discovery channel.
Workers and CLI runtime
The platform includes a Workers runtime with its own CLI reference, letting you deploy connection logic closer to where it runs rather than spinning up a full server to handle Notion API calls.
Best for
- teams building internal Notion automations without OAuth overhead
- SaaS developers who want to list a Notion integration on the Marketplace
- technical founders building AI agents that read or write Notion data
- solo developers scripting personal workflows with PATs and the CLI
- product engineers adding Notion as a data source or destination in their app
Skip if
- skip this if you need enterprise identity management — SCIM provisioning and SAML SSO are handled in Notion's Help Center, not through this API
- skip this if you want a no-code automation layer — this is a REST API with auth tokens, not a drag-and-drop builder
- skip this if your installation scope needs to change after creation — public connections lock their scope (any workspace vs. selected workspaces) at creation time and it can't be changed later
Pros & cons
Pros
- Three distinct auth models mean you're not forced to implement OAuth for a simple single-workspace script — internal connections and PATs cover the lighter-weight cases cleanly.
- The machine-readable documentation index at `/llms.txt` and first-class MCP support show genuine investment in AI-native developer workflows, not just a checkbox feature.
- Capability controls are configured per-connection, so you can ship a read-only integration without worrying about write permissions being accidentally exercised.
- The Marketplace path is well-defined: build a public connection, pass the security review, get listed — there's no ambiguity about what's required.
- A Postman workspace is provided out of the box, which cuts the time to your first successful API call significantly.
Cons
- Public connection installation scope is immutable after creation — if you build for 'selected workspaces only' and later want to go public, you're starting over.
- No pricing information is publicly surfaced for API access, so you can't evaluate cost before signing up or contacting Notion.
- The Workers and CLI reference exist, but the scraped documentation doesn't reveal runtime limits, pricing, or regional availability — key details that only surface after you're deeper into the docs.
- The Marketplace requires a Notion security review before listing, which adds an approval dependency that could block your launch timeline.
Frequently asked questions
What's the difference between an internal connection and a personal access token?
An internal connection is owned by the workspace and uses a static API token — multiple team members can manage it and it's not tied to any one user. A PAT is user-scoped, meaning it uses your Notion permissions and membership, making it better for personal scripts or CLI workflows where you're acting as yourself.
Do I need to go through the Marketplace to build a public connection?
No — you can create and use a public connection with OAuth 2.0 without ever listing it on the Marketplace. The Marketplace listing is optional and requires a Notion security review, but the connection itself works independently of that process.
Can I use the Notion API to build AI agents?
Yes — Notion ships dedicated Agent APIs and a native MCP (Model Context Protocol) server specifically for this use case, so you can connect AI agents to Notion's data layer without building a custom adapter.
What content can the REST API actually read and write?
The API covers pages, databases (including schemas and properties), views, comments, files, media, and users — essentially the full content model of a Notion workspace, not just a limited subset.
Where is SCIM or SAML SSO configuration handled?
Enterprise identity features like SCIM user provisioning, group management, and SAML SSO are not part of the Developer Platform API — Notion explicitly routes those to its Help Center, separate from these developer docs.
How Notion Developer Platform compares
Notion Developer Platform vs Zapier
Zapier gives you no-code Notion automation out of the box, but you're limited to its trigger/action model — if you need custom logic, database schema manipulation, or Agent API access, you'll hit its ceiling fast and need the Notion REST API directly.
Notion Developer Platform vs Airtable API
Airtable's API is more mature for structured database use cases and has clearer public pricing, but it doesn't offer an MCP server or native agent tooling, and its content model is narrower than Notion's pages-plus-databases approach.
Notion Developer Platform vs Confluence REST API
Confluence's API covers similar wiki-style content but is tightly coupled to the Atlassian ecosystem, lacks a Marketplace equivalent for third-party distribution, and doesn't have anything comparable to Notion's Agent APIs or MCP integration.
Reviews
No reviews yet — be the first.