Yes, Notion has a public REST API, with developer docs, a JavaScript SDK and four ways to connect: a personal access token, an internal connection, an OAuth integration or a public integration. Requests are rate limited per connection, and shared free workspaces can also hit a lifetime block limit on writes.
Yes, and there are four doors in
Notion's developer docs describe a REST API with an API reference and a JavaScript SDK. The interesting bit isn't whether there's an API, it's which way in you should use, because the choice changes what your tool can see and which limits apply to it.
| Route | Who it's for | How access works |
|---|---|---|
| Personal access token | Your own scripts and tools | Runs with your own Notion permissions, no separate sharing step |
| Internal connection | A tool your team shares | Has its own access; pages and databases must be shared with it |
| OAuth integration | Each user connects their own access | Limited to workspaces you select |
| Public integration | Apps for any workspace | Same OAuth flow, works in any workspace |
OAuth and public integrations use the same OAuth flow. The difference is reach: one is limited to selected workspaces, the other installs anywhere. Only public integrations can apply to be listed in Notion's own directory of integrations.
Conditions that decide whether it fits your job
Sharing pages with an internal connection
A capability on its own doesn't open every page. With an internal connection, you share each target page or database with it, either from the Content access tab in the Developer portal or with the Add connections option on the page in Notion. Forget this and your script returns nothing, which looks like a bug but isn't.
Request limits per connection
Each connection gets an allowance per 60-second window. Business and Enterprise workspaces get 600 requests per minute, an average of 10 per second. All other plans get 180 per minute, an average of 3 per second. Querying a data source has its own separate limit of about 3 requests per second per connection.
There's also a workspace-wide limit shared by every connection in the workspace. So one busy integration can cause rate limiting for another, even when each one is inside its own allowance. If two tools start failing at the same time, that's the first thing I'd look at.
Webhooks
Internal connections, OAuth integrations and public integrations can subscribe to webhooks for events such as page updates and new comments. A personal access token isn't on that list, so if you want Notion to tell your tool when something changes, pick one of the other three routes. If you're new to the difference, my explainer on how an API differs from a webhook helps.
The 1,000 block trap on shared free workspaces
This is the one that bites quietly. Notion's developer docs on workspace block limits say that free workspaces with more than one member have a limit of 1,000 lifetime blocks, as of Nov 2026, and it applies to API writes from internal connections and from OAuth connections restricted to selected workspaces. Deleting blocks doesn't give you capacity back.
Once the limit and a three-day grace period pass, an internal connection can't create blocks. Worse, queued templates can fail silently after the request has returned success, leaving a blank or half-filled page. Your logs say everything worked. The page says otherwise.
The limit doesn't apply to personal access tokens or to OAuth connections that can be installed in any workspace. That's the workaround if you're on a shared free workspace and writing a lot of content.
How to start without wasting a day
- Decide whose access the tool needs: yours alone, a shared team tool, or each user's own access.
- Create the token or connection in the developer portal and pick only the capabilities it needs, such as reading pages or updating databases.
- For an internal connection, share the target page or database with it.
- Run the Quickstart to create a first page with a personal access token, then move on to the API reference.
- Queue your requests and honour Retry-After on every 429 or 529 response, or use the JavaScript SDK, which does it for you.
When you go over the limit, Notion returns HTTP 429 with a rate_limited error and a Retry-After header in whole seconds. A 529 service_overload response should be retried the same way. Most of what you'll write to will be databases, so my guide to how Notion databases are structured is worth a look first.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
How other work tools set their API limits
monday.com's GraphQL API has a per-minute query limit that varies by plan, 5,000 on Enterprise, 2,500 on Pro and 1,000 on the rest, plus a daily call limit. Asana limits search API calls to 60 requests per minute and allows 5 concurrent duplication, instantiation or export jobs per user. If the API is the deciding factor, my list of Notion alternatives covers the wider field.
My advice before you write a single line of code
Start with a personal access token. It's the quickest route, it uses your own permissions and it sidesteps the block limit. Only move to an internal connection when a team needs to share the tool, and when you do, share the pages with it on day one and build in retries from the start. That one habit saves most of the late-night debugging I see people do.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
Is the Notion API a REST API?
Yes. The docs describe a REST API, with a JavaScript SDK and an API reference.
What is the Notion API rate limit?
Each connection gets 600 requests per minute on Business and Enterprise workspaces and 180 per minute on all other plans, with a separate workspace-wide limit.
What happens when I hit the limit?
You get an HTTP 429 with a Retry-After header. Wait that many seconds and retry; the JavaScript SDK does this automatically.
Can I use the API just for my own scripts?
Yes. A personal access token is made for your own scripts and tools and uses your existing page permissions.
Does the API support webhooks?
Yes. Internal connections, OAuth integrations and public integrations can subscribe to webhooks for events like page updates and new comments.
