What we do
Tools
Industries
Department
How we workLet's talk →
Home/Notion/Notion API
Notion

Getting Started with the Notion API, and What Trips People Up

Notion's public API lets your code read and write pages, databases, blocks and comments. Every first call needs three things: a token, a page shared with your connection, and a version header. Most early errors come from missing one of them. After that, the hard parts are the newer data source model and building a sync that keeps up.

Your first call needs these three

A token. A workspace owner creates an internal connection in Notion's developer portal. The token is on its Configuration tab. Send it as Authorization: Bearer <token>.

app.notion.com/developers/connections New integration

Access to the page. A connection sees nothing until someone shares a page or database with it. Open the page, then the ••• menu, and add your connection. Child pages come with it.

••• Add connections

A version header. Every request needs Notion-Version. Use a current one (Notion's docs use 2026-03-11), and don't copy an old value from a 2023 tutorial.

Notion API errors and their usual causes

Work down this list before assuming the API is broken.

object_not_found on a page you can see

How you'll know: The ID is right and the page opens fine for you in the app.

Fix: The page isn't shared with your connection. Add it from the page's ••• menu under Add connections. Your own access doesn't count, because the token acts as the connection, not as you.

Database calls fail after someone edits the database

How you'll know: Creating pages in a database, or querying it, suddenly returns errors, and search stops finding it.

Fix: Since version 2025-09-03, a database is a container holding one or more data sources, each with its own schema. Older versions break once a database gets a second data source. Upgrade the version, look up the data_source_id by retrieving the database, and query with PATCH /v1/data_sources/{id}/query.

validation_error on a long description or a big import

How you'll know: Short test values work, real data doesn't.

Fix: Each rich text item holds at most 2,000 characters, a block array at most 100 elements, and a relation 100 pages per request. A payload tops out at 1,000 blocks and 500 KB. Split long text into several rich text items and append blocks in batches.

HTTP 429 during a backfill

How you'll know: The first few hundred calls work, then everything returns rate_limited.

Fix: Most plans get 180 requests a minute per connection, Business and Enterprise 600, and data source queries about three a second on top of a shared workspace budget. Read Retry-After (in seconds), back off, and pace the job instead of running it in parallel.

A property won't update

How you'll know: Writes to a formula, rollup, created time or last edited value are rejected.

Fix: Those are computed by Notion and read-only through the API. Write the inputs the formula or rollup depends on instead.

An internal connection or a public integration?

Internal connection

Your own workspace

  • One workspace, one static token, set up by a workspace owner.
  • Sees only what people share with it.
  • Right for team automations, syncs and internal tools.
Public integration

Other people's workspaces

  • Uses OAuth 2.0, so each user authorizes it and picks the pages it can see.
  • Installs in any workspace, and you don't need a marketplace listing to start.
  • Right when you're building a product other teams will connect to Notion.

If the only workspace involved is yours, an internal connection is less work and nothing about it gets in your way later.

Notion webhooks: what arrives, and when

Notion now sends webhook events to connections. You add a subscription on your connection's Webhooks tab, give it a public HTTPS URL, and confirm it by pasting back a verification_token Notion posts to that URL. Each later event carries an X-Notion-Signature header, an HMAC-SHA256 of the body, which you should check.

There are events for pages (page.created, page.properties_updated, page.deleted and more), data sources, databases and comments. Each payload carries IDs, not content, so your handler fetches the page to see what changed.

Three things to design for. Many events are batched over about a minute, so a burst of edits arrives as one event. There's no ordering guarantee, so sort by the event timestamp. And if your endpoint doesn't answer, Notion retries up to eight times over about a day, then gives up. A sync that has to be right still needs a periodic check against the source.

Before you build a two-way sync with Notion

These decide whether the sync stays trustworthy after the first month.

  • Which system wins when both sides change the same field?

    Pick one owner per field. Two-way on every field is how loops and overwrites start.

  • Where will you store the ID pairs?

    Matching on names breaks the first time someone renames a page. Keep the Notion page ID next to the other system's record ID.

  • How do Notion property types map to your fields?

    A misspelled select value can turn into a new option, people fields need Notion user IDs, and dates carry time zones. Decide this before writing code.

  • What happens when a webhook is missed?

    Events can be retried and then dropped. A scheduled reconcile that compares recent edits catches what slipped through.

  • Who upgrades the Notion version next time?

    The data sources change broke integrations nobody was watching. Someone has to own the version header.

Questions people ask

Does Notion have a public API?

It does. Notion's REST API reads and writes pages, databases and their data sources, blocks, comments and users. You authenticate with an internal connection's token for your own workspace, or OAuth for a public integration.

Do I need to code to use the Notion API?

Using it directly, you do: it's HTTP requests with JSON, and Notion's JavaScript SDK makes them easier. Tools like Zapier or Make wrap some of the API for simple jobs. For a sync with real field mapping, error handling and upkeep, n-frames builds and maintains it so your team doesn't have to.

Does Notion support webhooks?

Notion connections can subscribe to webhook events for pages, data sources, databases and comments. Events carry IDs rather than content, many are batched over about a minute, and they can arrive out of order, so fetch the latest data when one arrives.

What can I build with the Notion API?

Anything that reads or writes Notion content: pages created when a deal closes or a job is booked, a database kept in step with a CRM or ops system, a dashboard outside Notion built from Notion data, or comments posted from another tool. See Notion integrations for common pairings.

What's the difference between a database ID and a data source ID?

From version 2025-09-03, a database is the container you see on the page and a data source is a table with its own schema inside it. Querying, creating pages and writing relations use the data_source_id. Retrieve the database to list its data sources and their IDs.

Why does the Notion API say it can't find my page?

Almost always because the page hasn't been shared with your connection. Open it, choose Add connections from the ••• menu, and pick yours. Pages inside a shared page are covered too.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.