Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท API and Integrations

Notion API Basics

Learn how the Notion API works: REST endpoints, JSON objects for pages, databases and blocks, the version header, rate limits, and what it can and cannot do.

The Notion app is for people. The Notion API is for programs. It lets a script read pages, query databases, add rows and edit blocks, so you can sync Notion with other tools, import data or build small internal apps.

The API is a normal web API: you send HTTPS requests with JSON and get JSON back. Notion's servers are not reachable from this site, so no example here calls the real API. The code is runnable JavaScript that builds requests and parses example responses we wrote ourselves, and every such block is labelled as a stand-in. Check Notion's developer documentation for the current field names and versions before you build.

The basics

Item Value
Base URL https://api.notion.com/v1
Format JSON over HTTPS
Authentication Authorization: Bearer <token> header
Version Notion-Version: <date> header (for example 2022-06-28)
Content type Content-Type: application/json for requests with a body

The version header matters. Notion releases API versions named after dates, and behavior can change between them (newer versions introduced new data source concepts for databases, for instance). Always send the version you tested with so your code does not change under you.

Objects you will meet

Everything is an object with "object" set to its kind and an id (a UUID):

  • Page: a page, or a row of a database. Its properties hold the database columns' values.
  • Database: the schema (property definitions) and a container for pages.
  • Block: a piece of page content: paragraph, heading, to-do, toggle, image and so on. Blocks can have children.
  • User: a person or a bot (an integration).
  • List: a wrapper for paginated results.

Properties are typed. A Title property looks like {"title": [{"text": {"content": "Hello"}}]}, a Select is {"select": {"name": "High"}}, a Checkbox is {"checkbox": true}. This is more verbose than the app suggests, so learning the shapes is half the work.

Main endpoints

Task Method and path
Retrieve a page GET /pages/{page_id}
Create a page POST /pages
Update page properties PATCH /pages/{page_id}
Query a database POST /databases/{database_id}/query
Retrieve a block's children GET /blocks/{block_id}/children
Append blocks PATCH /blocks/{block_id}/children
Search the workspace POST /search
List users GET /users

Newer API versions move database querying toward data sources, so use the path your chosen version documents.

Stand-in: build a request

This JavaScript only builds a request object and prints it; it does not send anything. That keeps it safe to run anywhere and shows exactly what a real call needs.

JS Stand-in: build a request

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Rate limits and errors

Notion limits requests to an average of about three per second per integration. If you exceed it you get HTTP 429 with a Retry-After header; wait that many seconds and try again. Other common errors:

Status Meaning
400 Invalid request: wrong property shape or missing field
401 Bad or missing token
403 The integration lacks the capability for that action
404 The object does not exist, or the integration has not been shared on it
409 Conflict; retry
429 Rate limited

The 404 surprise catches almost everyone: an integration can only see pages that have been shared with it, as the next lesson shows.

Stand-in: parse a list response

Responses are wrapped in a list object with pagination fields. This block uses a hand-written sample (not real data) to show how to read it.

JS Stand-in: read a list response

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What the API is good at, and what it is not

Good at: syncing with other systems, bulk imports, scheduled reports, form-to-database pipelines, building dashboards from Notion data.

Not designed for: very high request volume, real-time collaboration, or controlling the Notion interface itself. It also does not reproduce every feature; some app features have no endpoint, or only appear in newer versions.

Treat tokens like passwords. Never paste a real token into code you publish, a shared page, a screenshot or a chat. Keep it in an environment variable or a secrets manager.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which header selects the API behavior you tested against?

    Notion-Version takes a date string such as 2022-06-28 and pins behavior.
  2. 2. You get HTTP 404 for a page you can see in the app. What is a likely cause?

    Integrations see only pages that were shared with them, so missing access appears as 404.
  3. 3. What should you do after a 429 response?

    A 429 means rate limited; honor Retry-After before sending again.

Summary

  • The API is JSON over HTTPS at https://api.notion.com/v1 with a Bearer token and a Notion-Version header.
  • Core objects are pages, databases, blocks, users and lists, and properties are typed JSON.
  • Expect roughly three requests per second; handle 429 with Retry-After.
  • A 404 often means the integration was not given access to the page.

Next: Creating an Integration and Sharing Pages