Notion API - a complete, practical guide to integrations, pages, databases, blocks, search, and webhooks

The Notion API is a public HTTP API that lets your software integrate with Notion workspaces. You create an integration in Notion, receive an access token, and then call REST endpoints to read or write content such as pages, databases, and blocks. Notion’s reference introduction describes integrations as the way developers access Notion’s pages, databases, and users and build experiences that connect services to Notion. (See the API intro.)

A key idea: integrations only see what’s shared with them. Your integration will not automatically access a whole workspace. Users (or admins) must explicitly share pages/databases with the integration, and then the API can read and write within those shared areas. This permission boundary is one reason Notion integrations tend to be safer than “global” API keys.

The Notion API is flexible, but it shines in a few common patterns:

This quickstart shows the “happy path” for most Notion API projects: (1) create an integration and get a token, (2) share a database with the integration, (3) query the database, and (4) create a new page inside it.

1. Create an integration in Notion (internal or public). Notion’s Help Center walks through creating integrations and permissions.
2. Copy the token (for internal integrations) or implement OAuth for public integrations.
3. Share the target page/database with the integration in Notion UI (so the integration can access it).
4. Call the API with required headers: Authorization: Bearer ..., Notion-Version: 2025-09-03, and Content-Type: application/json where needed.

Example: query a database (POST /v1/databases/<id>/query)

curl -X POST "https://api.notion.com/v1/databases/YOUR_DATABASE_ID/query" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  --data '{
    "page_size": 10,
    "sorts": [{"timestamp":"last_edited_time","direction":"descending"}]
  }'

The database query endpoint returns pages in that database (and in newer structures, it can also return databases in wiki-like structures). The official reference explains that the response may contain fewer than page_size results and includes next_cursor for pagination. (Database query docs.)

Example: create a page in a database (POST /v1/pages)

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  --data '{
    "parent": { "database_id": "YOUR_DATABASE_ID" },
    "properties": {
      "Name": { "title": [{ "text": { "content": "Hello from the Notion API" } }] },
      "Status": { "select": { "name": "To do" } }
    }
  }'

The most common failure in this step is property mismatch: your payload must match the database property schema (property names, types, and allowed options). In this guide, you’ll learn how to safely build payloads by first retrieving the database schema.

Notion’s authentication documentation is straightforward: requests use the HTTP Authorization header to authenticate, and the API accepts Bearer tokens in that header. These tokens come from your integration (internal) or are issued via OAuth for public integrations. (Authentication docs.)

Tokens should be treated like passwords. Do not commit them to Git, do not place them in client-side JavaScript, and never ship them to end users. Use environment variables and a secure secret manager for production.

Notion distinguishes between internal integrations (used within a single workspace) and public integrations (distributed to many workspaces). The authorization process differs: internal integrations typically use a static token created in the integration settings, while public integrations use OAuth so each user/workspace grants access and your app receives tokens per installation. Notion’s authorization documentation explains this distinction and notes special handling for link preview integrations. (Authorization docs.)

Notion’s API is versioned. The versioning documentation states that versions are named for the date they’re released, and it explicitly gives 2025-09-03 as the latest version (at the time of the doc). You set the version with the required Notion-Version header. (Versioning docs.)

If you’re updating an older integration, Notion publishes upgrade guides. For example, the “Upgrading to Version 2025-09-03” guide describes changes and suggests a migration process, including updating calls to newer database APIs and using the 2025-09-03 version header during migration. (Upgrade guide.)

Versioning best practices

• Pin a version. Always set Notion-Version explicitly in your HTTP client.
• Read upgrade guides. When Notion announces a new version, scan what changed before you flip the header globally.
• Test in a staging workspace. Use a separate Notion workspace to validate changes before production.
• Log the version. Include the version in your logs so incidents are easier to debug.

Notion access has two layers:

• Integration capabilities (scopes/permissions): what types of objects/actions the integration is allowed to request.
• Shared content boundary: which pages/databases a user has explicitly shared with the integration in the Notion UI.

In practice, you often get “permission denied” errors because one of these layers is missing: either the integration doesn’t have the correct capabilities (e.g., “read content” vs “insert content”), or the page/database wasn’t shared with the integration.

Understanding Notion’s object model will save you days of confusion:

Many integrations follow a “schema-first” approach: retrieve the database schema (Get Database), then generate payloads that match it. This helps you avoid hardcoding property types and reduces breaking changes when someone edits the database in Notion.

Notion’s API reference is organized by object type and endpoint. Most integrations use a subset of these endpoints:

Databases are where most Notion API projects live. A typical integration does these steps: (1) retrieve the database to read its schema, then (2) query the database with filters and sorts, then (3) create or update pages (rows) in that database.

Query a database

Notion’s database query endpoint is a POST call where you can supply filters and sorts. The reference notes the response may include next_cursor and that you should use cursor-based pagination to iterate. (Database query docs.)

Example: query with filter + pagination fields

{
  "page_size": 50,
  "filter": {
    "and": [
      { "property": "Status", "select": { "equals": "In progress" } },
      { "property": "Priority", "select": { "does_not_equal": "Low" } }
    ]
  },
  "sorts": [
    { "timestamp": "last_edited_time", "direction": "descending" }
  ]
}

Notion property payloads are strict. You must send the right shape for each property type. The safest approach is:

1. Retrieve the database schema first (Get Database) and inspect property types.
2. Build payloads by type (title, rich_text, select, multi_select, date, number, people, relation, files, checkbox, etc.).
3. Validate inputs in your app so you never send illegal values (like a Select option that doesn’t exist).

Pages are central to Notion. When a page lives inside a database, you typically interact with it through its properties. When you want to edit the body of the page (paragraphs, headings, lists), you work with blocks.

Example: update a page property (PATCH /v1/pages/<id>)

{
  "properties": {
    "Status": { "select": { "name": "Done" } },
    "Reviewed": { "checkbox": true }
  }
}

Blocks represent the actual content on a page: text, headings, bullet lists, to-dos, images, toggles, callouts, code blocks, tables, and more. If you’re building a publisher, exporter, or document automation, blocks are where you’ll spend most of your time.

Notion’s “Working with page content” guide shows that retrieving block children is paginated, with a maximum of 100 results per response, and you use start_cursor and page_size to fetch additional results. (Working with page content guide.)

Example: append blocks (high-level)

{
  "children": [
    { "object": "block", "type": "heading_2", "heading_2": { "rich_text": [{ "type":"text","text":{"content":"Summary"}}] } },
    { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "type":"text","text":{"content":"Generated by my integration."}}] } },
    { "object": "block", "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{ "type":"text","text":{"content":"First bullet"}}] } }
  ]
}

Search is the easiest way to locate objects your integration has access to, especially when you don’t know IDs. The search reference notes it supports pagination and points to the API introduction for pagination behavior. (Search reference.)

Example: search by text query

{
  "query": "Editorial Calendar",
  "sort": {
    "direction": "descending",
    "timestamp": "last_edited_time"
  }
}

Practical uses for Search:

• Find the database a user wants to connect by name/title.
• List “available” pages shared with your integration during setup.
• Build a lightweight internal “Notion object picker” UI.

The comments guide explains that you can list comments for a page or block using the block_id query parameter, because pages are technically blocks. It also notes the endpoint returns a flat list and that some block types may support multiple discussion threads. (Comments guide.)

Notion exposes user objects for people who appear in properties (like “Assignee”). Integrations often need users to:

• Assign tasks (people property)
• Show who created or edited pages (metadata)
• Map Notion users to internal users in your system (SSO or email matching when possible)

In multi-tenant apps, avoid assuming an email address is always available or stable. Use Notion user IDs as primary identifiers and store mappings in your database.

Notion uses cursor-based pagination across many “list” endpoints (database query results, search results, block children, comments lists, etc.). The “Working with page content” guide notes that paginated responses are used throughout the API and the maximum results per response is 100, and it references using start_cursor and page_size to retrieve more than 100 results. (Working with page content guide.)

The standard loop looks like this:

let cursor = undefined;
do {
  const body = cursor ? { start_cursor: cursor, page_size: 100 } : { page_size: 100 };
  const res = await callNotion(endpoint, body);
  handle(res.results);
  cursor = res.next_cursor; // null/undefined when done
} while (cursor);

Notion’s request limits documentation says requests that exceed limits return a rate_limited error (HTTP 429), and it states the rate limit for incoming requests per integration is an average of three requests per second. It also says you should respect the Retry-After header (seconds). (Request limits docs.)

Example retry strategy (human-readable)

• On 429: read Retry-After → wait that many seconds → retry.
• Also implement exponential backoff for transient 5xx or network timeouts.
• Make writes idempotent where possible (avoid duplicate page creation on retry).

A production Notion integration is mostly error handling and data hygiene. Your app should gracefully handle:

Webhooks let your integration receive real-time updates from Notion. Notion’s webhook reference says that when a page or database changes, Notion sends a secure HTTP POST request to your webhook endpoint so your application can respond as it happens. (Webhooks reference.)

Notion also documents that webhook events are signals rather than full diffs: the “Event types & delivery” page explains events do not contain the full content that changed, and your integration should follow up with API calls to retrieve the latest content. (Events & delivery docs.)

Notion’s Help Center also covers “integration webhooks” in more user-facing language, emphasizing they enable integrations to respond to changes in shared pages/databases in real time. (Help Center integrations page.)

Treat Notion like any SaaS with privileged access:

• Never expose tokens in the browser. Notion tokens must stay server-side.
• Use least privilege permissions. Only request the scopes you need.
• Encrypt tokens at rest. Use a KMS or managed secret store.
• Log safely. Never log tokens or full Notion content if it includes sensitive data.
• Validate input. Defend against injection in any content you write into Notion (especially if rendering elsewhere).
• Verify webhooks. Validate signatures/headers per Notion webhook docs before trusting events.

The Notion API is powerful, but you’ll hit rate limits (3 rps average per integration) quickly if you do naive polling or page-by-page traversal. (Request limits docs.) The scalable pattern is a sync engine with caching and incremental updates:

Performance tips that actually matter

• Batch reads with concurrency limits. Use a small pool (e.g., 2–4 concurrent calls) + a global rate limiter.
• Prefer database queries over search for structured lists. Search is great for discovery, but query is better for deterministic retrieval. (Search docs, Database query docs.)
• Cache block trees. Blocks retrieval is paginated and can be expensive on long pages. (Working with page content guide.)
• Use checkpoints. Track last successful sync times and update windows to prevent missed changes.
• Make writes idempotent. Store an external_id property or use stable keys to avoid duplicates on retries.

• Notion Developers home
• API Reference: Introduction
• Authentication (Bearer tokens)
• Authorization (internal vs public/OAuth)
• Versioning (Notion-Version required; latest 2025-09-03)
• Request limits (3 rps avg, 429, Retry-After)
• Search endpoint
• Query a database endpoint
• Working with page content (pagination, blocks)
• Working with comments (pages are blocks)
• Webhooks overview
• Webhook events & delivery (fetch changes via API)
• Upgrade guide: 2025-09-03