Notion Advanced Troubleshooting

Overview

Deep debugging techniques for Notion API issues that resist standard fixes — API response inspection with request IDs, permission chain tracing, property type mismatch detection, pagination edge cases, and block nesting limit violations (max depth of 3 levels via API). Full runnable TypeScript and Python for every step lives in references/implementation.md.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Python: notion-client installed (pip install notion-client)
• curl available for raw API testing
• NOTION_TOKEN environment variable set (internal integration token starting with ntn_)
• Pages/databases shared with your integration via Notion UI

Authentication

All calls authenticate with a single internal integration token in the NOTION_TOKEN environment variable — the SDK reads it via auth: process.env.NOTION_TOKEN, and raw curl sends it as Authorization: Bearer $NOTION_TOKEN plus the Notion-Version: 2022-06-28 header. Never hardcode the token; keep it in the environment. Confirm the token is a bot token with notion.users.me() — if the returned type is not bot, the token is wrong. A 401 unauthorized means a bad/expired token; a 404 object_not_found on a valid page means the token is fine but the resource was never shared with the integration (see Step 2).

Instructions

Work the steps in order — each narrows where the failure lives. Read the full walkthrough for the complete function bodies; the skeletons below show the entry point of each.

Step 1: API Response Inspection with Request ID Tracking

Every Notion API response carries an x-request-id header. Enable LogLevel.DEBUG and wrap calls so every request logs its ID and timing — capture that ID for support tickets. Use Grep over the debug log to find a specific request's ID after the fact.

const notion = new Client({ auth: process.env.NOTION_TOKEN, logLevel: LogLevel.DEBUG });

async function tracedCall<T>(label: string, fn: () => Promise<T>) {
  const start = Date.now();
  try {
    const result = await fn();
    console.log(`[${label}] OK ${Date.now() - start}ms`);
    return result;
  } catch (error) {
    if (isNotionClientError(error)) console.error(`[${label}] FAILED`, error.code, error.body);
    throw error;
  }
}

To isolate SDK-vs-transport bugs, replay the same call with raw curl and compare — full curl recipe and the Python traced_call equivalent …

Notion Architecture Variants

Overview

Five validated architecture patterns for using Notion as a backend via the API, each with database schema design, integration code, and deployment tradeoffs. The full copy-ready code for every variant lives in references/implementation.md; this page gives the decision framework, the shared skeleton, and one worked example so you can pick the right pattern and drill into depth on demand.

The five variants:

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN environment variable set
• Notion databases created and shared with your integration

Authentication

All variants authenticate the same way: an internal integration token in the NOTION_TOKEN environment variable, passed as auth when constructing the client (new Client({ auth: process.env.NOTION_TOKEN }) / Client(auth=...)). Create the integration at notion.so/my-integrations, then share each database with the integration from its Notion page — an unshared database returns object_not_found even with a valid token. Never hard-code the token; read it from the environment.

Instructions

1. Pick the variant that matches your workload using the decision helper in references/examples.md — content authoring vs. real-time status vs. high read volume each point to a different pattern.
2. Model the database schema in Notion for that variant (property names and types are documented inline with each variant's code). Share the database with your integration.
3. Read any existing integration module, then Write the client setup: construct one Client with auth: process.env.NOTION_TOKEN and reference each database by its own NOTION_*_DB env var.
4. …

Notion CI Integration

Overview

Integrate the Notion API into CI/CD pipelines for automated documentation sync, deploy tracking, and configuration reads. GitHub Actions workflows push release notes to Notion pages, upsert deploy entries in databases, create incident pages, and read feature flags — all with rate-limit handling, and each concern in its own reference file for copy-ready code.

Prerequisites

• GitHub repository with Actions enabled
• Notion internal integration token (create at https://www.notion.so/my-integrations)
• Target Notion pages/databases shared with the integration (click "..." > "Connections" > add the integration)
• NOTION_TOKEN stored as a GitHub Actions secret
• Node.js 18+ or Python 3.9+ in the CI environment

Authentication

Every request authenticates with an internal integration token passed as a bearer credential. The Notion SDKs read it from the NOTION_TOKEN environment variable (new Client({ auth: process.env.NOTION_TOKEN }) in Node, Client(auth=token) in Python). Store it as a repository secret and inject it per job — never hardcode it (gh secret set NOTION_TOKEN). A token only reaches pages and databases explicitly shared with the integration (page menu > "Connections" > add integration); an unshared target returns 404 Object not found, not 401 — see Error Handling.

Instructions

The integration is three composable pieces — read each summary for its shape, then open the linked reference for complete, copy-ready code.

Step 1: Workflow for documentation sync

Add a workflow that reacts to release: published and pushes to main. It runs three jobs — create a release-notes page, sync the CHANGELOG.md page, and update the deploy tracker — each injecting NOTION_TOKEN and the relevant database ID as env:

# .github/workflows/notion-docs-sync.yml
on:
  release: { types: [published] }
env:
  NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
jobs:
  sync-release-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4      # + npm ci (see reference)
      - run: node scripts/notion-release-sync.js
        env:
          NOTION_RELEASES_DB: ${{ secrets.NOTION_RELEASES_DB }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}

See full workflow YAML for all three jobs, the changelog push trigger, and the needs:-gated deploy-status job.

Step 2: CI scripts for Notion operations

Back the workflow with small scripts. The release-notes script creates a database page and appends the body as blocks …

Notion Common Errors

Overview

Quick reference for all Notion API error codes with exact HTTP statuses, error bodies, and fixes. The API returns errors as JSON with three fields:

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Title is not a property that exists."
}

All requests require Authorization: Bearer $NOTION_TOKEN and Notion-Version: 2022-06-28 headers (2022-06-28 is the current stable API version — the header is required on every call).

This SKILL.md gives you the triage table and workflow. Two references carry the depth:

• references/error-codes.md — the full per-status playbook (401, 403, 404, 400, 429, 409, 500, 502/503) with error bodies, causes, and code fixes.
• references/examples.md — the full SDK error handler, the curl diagnostic script, and the non-HTTP client-side gotchas (rich text arrays, pagination, timeouts).

Prerequisites

• @notionhq/client installed (npm install @notionhq/client)
• NOTION_TOKEN environment variable set (internal integration token starting with ntn_ or secret_)
• Target pages/databases shared with the integration via the Connections menu

Instructions

Step 1: Identify the Error

1. Read the JSON error body returned by the failed request.
2. Note its HTTP status and machine-readable code fields — those two values route you to the exact fix.
3. If you only have logs, Grep your application logs for the code field to recover the values.

Step 2: Match Error Code and Apply Fix

Use the Error Handling table below to see whether the error is retryable and the recommended action. For the exact error body, root cause, and copy-paste fix, open the matching section in references/error-codes.md. The four you will hit most:

• 404 object_not_found — the most common error. The page/database exists but is not shared with your integration. Fix via the ... → Connections menu; parent pages must be shared too.
• 401 unauthorized — token missing, malformed, expired, or revoked. Verify with curl .../v1/users/me; regenerate at notion.so/my-integrations.
• 400 validation_error — the broadest category, usually a wrong property name/type or a filter-type mismatch (e.g. status: fil…

Notion Content Management

Overview

Complete guide to creating, updating, archiving, and composing Notion pages and block content using the @notionhq/client SDK. Covers page lifecycle, all common block types, rich text formatting, and bulk content operations. The core workflow lives here at a high level; deep code walkthroughs are extracted into references/ so this file stays scannable.

Prerequisites

• Completed notion-install-auth setup
• NOTION_TOKEN environment variable set
• Target database or page shared with the integration (via Connections menu)
• @notionhq/client v2+ installed (TypeScript) or notion-client (Python)

Instructions

Step 1: Create, Update, and Archive Pages

Create a page in a database with typed properties (title, select, multi_select, date, people, number, checkbox, url), an optional icon/cover, and initial children block content. Update properties with pages.update (set a property to null to clear it). Archive is a soft-delete via archived: true, and restore flips it back to false.

Minimal skeleton:

import { Client } from '@notionhq/client';
const notion = new Client({ auth: process.env.NOTION_TOKEN });

const page = await notion.pages.create({
  parent: { database_id: databaseId },
  properties: { Name: { title: [{ text: { content: 'Q1 Retro' } }] } },
});
await notion.pages.update({ page_id: page.id, properties: { Status: { select: { name: 'Done' } } } });
await notion.pages.update({ page_id: page.id, archived: true });  // archive

Full typed-property create, update-with-clear, and archive/restore functions: page lifecycle walkthrough.

Step 2: Compose Content with Block Types

Append blocks to an existing page with blocks.children.append. Each block type has its own payload shape — headings, paragraphs (with rich text annotations), bulleted/numbered lists, to-dos, toggles, code blocks, callouts, quotes, dividers, images, and tables are all supported. The full catalog with the exact shape for every block type is in the block type catalog.

The minimal pattern:

await notion.blocks.children.append({
  block_id: pageId,
  children: [
    { heading_2: { rich_text: [{ text: { content: 'Notes' } }] } },
    {
      paragraph: {
        rich_text: [
          { text: { content: 'Plain and ' } },
          { text: { content: 'bold' }, annotations: { bold: true } },
        ],
      },
    }…

Notion Core Workflow A — Databases & Pages

Overview

Primary workflow for Notion integrations: querying databases with filters/sorts, creating pages with typed properties, updating page properties, and retrieving page content.

Prerequisites

• Completed notion-install-auth setup
• A Notion database shared with your integration
• Understanding of your database's property schema

Authentication

Every call below uses a Client authenticated with an integration token (process.env.NOTION_TOKEN). Token creation, secret storage, and sharing a database with the integration are covered end-to-end in the notion-install-auth skill — complete it first. Never hardcode the token; read it from the environment.

Instructions

The workflow is six steps. Steps 1–2 (schema + filtered query) are the skeleton you almost always start with, shown here in full. Steps 3–6 (filter syntax by type, page creation, updates/archive, pagination) live in the full walkthrough so this file stays scannable.

Step 1: Retrieve Database Schema

Always inspect the schema first — property names and types drive every filter and write. databases.retrieve returns db.properties keyed by property name.

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function getDatabaseSchema(databaseId: string) {
  const db = await notion.databases.retrieve({ database_id: databaseId });
  for (const [name, prop] of Object.entries(db.properties)) {
    console.log(`${name}: ${prop.type}`);
    if (prop.type === 'select') {
      console.log('  Options:', prop.select.options.map(o => o.name));
    }
  }
  return db.properties;
}

Step 2: Query with Filters

Notion filters use a nested structure keyed by property type, and combine with and / or. sorts and page_size (max 100) tune the result set.

async function queryWithFilters(databaseId: string) {
  const response = await notion.databases.query({
    database_id: databaseId,
    filter: {
      and: [
        { property: 'Status', select: { equals: 'In Progress' } },
        { property: 'Priority', select: { does_not_equal: 'Low' } },
      ],
    },
    sorts: [{ property: 'Priority', direction: 'ascending' }],
    page_size: 50,
  });
  return response.results;
}

Steps 3–6: Filter syntax, create, update, paginate

See the full walkthrough for copy-paste code:

• Step 3 — Filter syntax by property type. Every property type (text, number, …

Notion Core Workflow B — Blocks, Content & Comments

Overview

Secondary workflow for content operations: reading block trees, appending content, building rich text with annotations, and managing comments. SKILL.md keeps the flow at a high level; every full implementation lives in references/implementation.md.

Prerequisites

• Completed notion-install-auth setup
• A Notion page shared with your integration
• Familiarity with notion-core-workflow-a (databases/pages)

Authentication

All calls use the @notionhq/client SDK authenticated with an integration token read from process.env.NOTION_TOKEN. The token is provisioned by the notion-install-auth skill (internal integration secret) — do not hard-code it. The page or block being edited must be explicitly shared with that integration, or calls return object_not_found.

Instructions

The workflow has six steps. The client is created once and reused:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

1. Retrieve block children — page through notion.blocks.children.list with a start_cursor loop (100 blocks/page) until has_more is false.
2. Read blocks recursively — walk each block, and when has_children is true recurse to build a nested tree; blockToText flattens a block's rich_text to a plain string.
3. Append content blocks — one notion.blocks.children.append call adds headings, formatted paragraphs, bulleted/numbered lists, to-dos, code, callouts, quotes, dividers, and toggles.
4. Rich text annotations — each rich-text span carries annotations (bold, italic, strikethrough, underline, code, color); spans can be plain text, links, user/page/date mentions, or LaTeX equations.
5. Update and delete blocks — notion.blocks.update replaces a block's content; notion.blocks.delete archives it.
6. Work with comments — notion.comments.create adds page or discussion-thread comments; notion.comments.list reads them back.

Each step's complete, copy-paste code is in references/implementation.md.

Output

• Page content blocks retrieved (flat or recursive tree)
• Rich content appended with formatting, lists, code, callouts
• Blocks updated and deleted
• Comments created and listed

Error Handling

Notion Cost Tuning

Overview

The Notion API is free with every workspace plan — there is no per-call pricing. The real "cost" is the 3 requests/second rate limit (per integration token) plus the engineering time wasted on inefficient patterns. Apply the six strategies below to reduce request volume by 80-95%.

Notion workspace pricing (for context — API access is included at every tier):

The rate limit is identical across all plans. Optimization is about staying within 3 req/sec, not reducing a bill.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Integration token from notion.so/my-integrations
• Token shared with target pages/databases via the Connections menu in Notion
• For queue patterns: p-queue v8+ (npm install p-queue)
• For caching: node-cache or lru-cache (npm install lru-cache)

Authentication

Every technique here uses the same auth as any Notion integration: a single bearer token passed to the client constructor. Store it in an environment variable (NOTION_TOKEN) — never hardcode it — and share it with each target page/database through the Connections menu. One token = one 3 req/sec budget; provision a separate integration token per service when you need independent budgets.

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Instructions

Work the three steps in order. Each links to the full, copy-paste-ready code in references/implementation.md; the essentials are inlined below so you can follow the flow from here.

Step 1: Audit current request volume

Measure before optimizing. Wrap every Notion call in a tracker that records method, endpoint, timestamp, and duration, then print a per-minute report to find the operations eating > 50% of your budget (usually polling loops, redundant retrieves, and full-table scans).

async function tracked<T>(method: string, fn: () => Promise<T>): Promise<T> {
  const start = Date.now();
  try {
    return await fn();
  } finally {
    requestLog.push({ method, timestam…

Notion Data Handling

Overview

Handle sensitive data correctly when integrating with Notion: detect PII in page properties and text content, redact sensitive fields before logging or exporting, minimize data exposure with filter_properties, and implement GDPR/CCPA compliance patterns — right-of-access exports, right-of-deletion (archive or field clearing), and retention-based archival, all with audit logging.

The full, copy-ready TypeScript and Python implementations live in references/ so this file stays a navigable map. Read top-to-bottom for the workflow; drill into a reference file when you need the complete code for a step.

Prerequisites

• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• Understanding of which Notion databases contain personal data
• Audit logging infrastructure (structured logs, SIEM, or Notion audit database)
• Legal guidance on applicable regulations (GDPR, CCPA, HIPAA, etc.)

Authentication

All examples authenticate with an internal integration token read from the environment — never hardcode it:

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Create the token at notion.so/my-integrations and share each target database with the integration. Deletion and retention flows additionally require the integration to hold Update capability, or pages.update returns 403.

Instructions

Work through three stages. Each links to a reference file with the complete implementation.

Step 1 — Detect PII

Notion pages carry PII in dedicated email/phone_number/people properties and embedded in free-text rich_text/title values. Scan both: check known-sensitive property types directly, and run regex matchers (email, phone, SSN, credit card, IP) over text. Loop the whole database through pagination until has_more is false. Skeleton:

function scanPageForPII(page: PageObjectResponse): PIIFinding[] {
  // check email / phone_number / people property types,
  // then run PII_PATTERNS regexes over rich_text + title text
}

Full TS + Python scanners: pii-detection.md.

Step 2 — Redact and minimize

Never log or export raw page objects. Pass every page through an allowlist-shaped redactor that masks sensitive property types and named fields while letting vetted scalar types pass through. Then cut exposure at the source with filter_properties, which returns only the properties you name:

Notion Debug Bundle

Overview

Collect diagnostic information for Notion API issues: SDK version, token validity, database access, page sharing status, rate limits, and platform health. The Notion API requires integrations to be explicitly invited to each page or database — most "not found" errors are sharing problems, not code bugs.

Prerequisites

• @notionhq/client installed (npm ls @notionhq/client to verify)
• NOTION_TOKEN environment variable set (internal integration token, starts with ntn_)
• curl and jq available for shell-based diagnostics

Instructions

Step 1: Quick Connectivity and Auth Check

#!/bin/bash
echo "=== Notion Debug Check ==="
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# 1. SDK version
echo -e "\n--- SDK Version ---"
npm ls @notionhq/client 2>/dev/null || echo "SDK not found — run: npm install @notionhq/client"

# 2. Runtime and token status
echo -e "\n--- Runtime ---"
node --version 2>/dev/null || echo "Node.js not found"
echo "NOTION_TOKEN: ${NOTION_TOKEN:+SET (${#NOTION_TOKEN} chars)}"
TOKEN_PREFIX="${NOTION_TOKEN:0:4}"
if [ -n "$NOTION_TOKEN" ] && [ "$TOKEN_PREFIX" != "ntn_" ]; then
  echo "WARNING: Token does not start with 'ntn_' — may be using legacy format"
fi

# 3. API connectivity — /v1/users/me as health check
# Notion-Version 2022-06-28 is the current stable REST API version.
echo -e "\n--- API Connectivity ---"
RESPONSE=$(curl -s -w "\n%{http_code}\n%{time_total}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" 2>&1)

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
LATENCY=$(echo "$RESPONSE" | tail -2 | head -1)
BODY=$(echo "$RESPONSE" | head -n -2)

echo "HTTP Status: $HTTP_CODE"
echo "Latency: ${LATENCY}s"

if [ "$HTTP_CODE" = "200" ]; then
  echo "Bot Name: $(echo "$BODY" | jq -r '.name // "unknown"')"
  echo "Bot Type: $(echo "$BODY" | jq -r '.type // "unknown"')"
else
  echo "Error Code: $(echo "$BODY" | jq -r '.code // "unknown"')"
  echo "Message: $(echo "$BODY" | jq -r '.message // "unknown"')"
fi

# 4. Notion platform status
echo -e "\n--- Notion Platform Status ---"
curl -s https://status.notion.so/api/v2/status.json \
  | jq -r '.status.description // "Could not reach status page"' 2>/dev/null \
  || echo "Could not reach status.notion.so"

# 5. Rate limit baseline (3 req/sec acr…

Deploy Notion-Integrated Applications

Overview

Ship Node.js apps that talk to the Notion API to Vercel, Railway, or Fly.io. This skill covers environment variable management, the Notion client singleton pattern for serverless, rate limit handling at 3 req/sec, health check endpoints that verify Notion connectivity, and caching strategies to reduce API calls.

Deep code lives in references/ so this file stays a lean walkthrough. Read a reference when a step needs the full module, then Write or Edit the code into your project's src/.

Prerequisites

• Node.js >= 18 project with @notionhq/client installed (npm i @notionhq/client)
• Working Notion integration tested locally with a valid NOTION_TOKEN (starts with ntn_)
• Platform CLI installed for your target: vercel, railway, or fly
• Database or page IDs your integration needs access to

Authentication

Every request authenticates with an internal integration token (NOTION_TOKEN, prefix ntn_), created at notion.so/my-integrations and passed as auth to the client. In production the token is stored as an encrypted platform secret and injected at runtime — never committed to source. Store it with vercel env add NOTION_TOKEN production, railway variables set NOTION_TOKEN=..., or fly secrets set NOTION_TOKEN=.... Each database or page must also be explicitly shared with the integration in the Notion UI, or queries return ObjectNotFound.

Instructions

Step 1 — Prepare the application for production

Build a production entry point with four modules: a Notion client singleton, a rate limiter, a response cache, and a health check. The singleton is the essential piece — serverless containers recycle unpredictably, so a module-level client reuses connections across warm invocations instead of paying cold-start and rate-limit cost per request:

// src/notion-client.ts — singleton for serverless environments
import { Client, LogLevel } from '@notionhq/client';

let client: Client | null = null;

export function getNotionClient(): Client {
  if (!client) {
    if (!process.env.NOTION_TOKEN) {
      throw new Error('NOTION_TOKEN environment variable is not set');
    }
    client = new Client({
      auth: process.env.NOTION_TOKEN,
      logLevel: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
      timeoutMs: 30_000,
    });
  }
  return client;
}

The rate limiter (token bucket for the 3 req/sec cap), the TTL response cache, and the healthCheck() function are provided in full — read production-ready application modules …

Notion Enterprise RBAC

Overview

Implement enterprise-grade access control for Notion integrations. This covers the full OAuth 2.0 authorization flow for public integrations (multi-tenant), per-workspace token storage with encryption at rest, Notion's page-level permission model and how to handle ObjectNotFound vs RestrictedResource, an application-level role system (admin/editor/viewer) layered on top of Notion's permissions, comprehensive audit logging to a Notion database, and workspace deauthorization cleanup.

Prerequisites

• Notion public integration created at <https://www.notion.so/my-integrations> (for OAuth)
• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• Database for storing per-workspace tokens (PostgreSQL, DynamoDB, etc.)
• HTTPS endpoint for OAuth callback (required by Notion)

Instructions

The workflow has three steps. Each is summarized here with its key entry point; the complete, copy-ready code for all three lives in the full implementation reference.

Step 1: OAuth 2.0 Authorization Flow

Notion uses OAuth 2.0 for public integrations to reach external workspaces. Build an authorization URL with a random state for CSRF protection, redirect the user, then on callback verify the state and exchange the code for a workspace access token. Notion's token endpoint uses HTTP Basic auth with your client id and secret:

function getAuthorizationUrl(state: string): string {
  const params = new URLSearchParams({
    client_id: process.env.NOTION_OAUTH_CLIENT_ID!,
    response_type: 'code',
    owner: 'user',       // 'user' = user-level token, 'workspace' = workspace-level
    redirect_uri: process.env.NOTION_REDIRECT_URI!,
    state,               // CSRF protection — must verify on callback
  });
  return `https://api.notion.com/v1/oauth/authorize?${params}`;
}

The token exchange returns access_token, bot_id (the primary key per installation), workspace_id, and owner metadata. A Python equivalent and the full Express callback handler are in the implementation reference.

Step 2: Token Storage and Permission-Aware API Calls

Store one token per bot_id (encrypt access_token at rest — use KMS or column-level encryption in production), and construct a per-workspace Client on demand. Wrap every page read so Notion's permission model is handled explicitly rather than crashing:

// ObjectNotFound = page exists but is NOT shared with the inte…

Notion Hello World

Overview

Three minimal examples covering the Notion API core surfaces: searching for pages, creating a test page in a database, and verifying the created page by retrieving it back.

Prerequisites

• Completed notion-install-auth setup
• NOTION_TOKEN environment variable set (internal integration token from <https://www.notion.so/my-integrations>)
• At least one database shared with your integration via the Connections menu
• Node.js 18+ with @notionhq/client or Python 3.8+ with notion-client

Authentication

Every request authenticates with your internal integration token via the NOTION_TOKEN environment variable — the client reads it as new Client({ auth: process.env.NOTION_TOKEN }) (or Python's Client(auth=os.environ["NOTION_TOKEN"])). Generate the token at notion.so/my-integrations, then share each target database with the integration through its Connections menu. Never hardcode the token — keep it in the environment. See notion-install-auth for the full setup.

Instructions

The workflow is three steps against the Notion API core surfaces. Instantiate the client once, then search, create, and verify. Step 1's skeleton is below; the full create + verify code (with block content, title extraction, and metadata) is in the implementation walkthrough.

Step 1: Search for pages

The search endpoint queries across everything your integration can access; filter narrows to pages (use value: 'database' for databases).

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const { results } = await notion.search({
  query: 'meeting notes',
  filter: { property: 'object', value: 'page' },
  page_size: 5,
});

Step 2: Create a test page

pages.create adds a row to a target database. The properties object must match the database schema — Name with type title is the only universally required property. An optional children array appends block content (headings, paragraphs, to-dos) at creation time. Full code is in the implementation walkthrough.

Step 3: Verify by retrieving the page

pages.retrieve fetches the full page object, confirming creation and exposing created_time, last_edited_time, url, and the complete properties map. Full code is in the implementation walkthrough.

Outpu…

Notion Incident Runbook

Overview

Rapid incident response for Notion API failures. This runbook drives a sub-5-minute triage that classifies the failure as Notion-side vs. integration-side, then routes to per-error-type mitigation, cached fallback, and a structured postmortem.

Deep material — full triage scripts, remediation code, and templates — lives in references/; this file is the high-level flow you follow live.

Prerequisites

• Access to application monitoring dashboards and log aggregator
• NOTION_TOKEN environment variable set for diagnostic API calls
• curl and jq installed for quick CLI triage
• Python alternative: notion-client (pip install notion-client)
• Communication channels configured (Slack webhook, PagerDuty, etc.)

Instructions

Step 1: Quick Triage (Under 5 Minutes)

At first alert, decide whether the fault is Notion's or yours. Check the platform status page, then test your own auth. This one call is enough to start:

curl -sf -o /dev/null -w "%{http_code}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28"   # 2022-06-28 = pinned Notion API version

Map the result: 200 → integration-side, 401 → token expired/revoked, 429 → rate limited, 000 → network/DNS. If status.notion.so shows an active incident, it is Notion-side regardless of your auth code.

Read references/triage.md for the full notion-triage.sh diagnostic (status page + auth + DB-query latency + auto-classification) and a TypeScript triageNotionHealth() equivalent for in-app health checks.

Step 2: Decision Tree and Mitigation

Route the classification to a remediation path:

• Notion-side outage — enable cached/fallback mode, notify users, monitor the status page. Do NOT restart or rotate tokens.
• 401 token expired/revoked — regenerate at notion.so/my-integrations, update the secret manager, restart the app.
• 429 rate limited — you are exceeding the 3 req/s average; find runaway loops or webhook storms, drop concurrency to 1, add exponential backoff.
• 404 on known resources — pages unshared or trashed; re-share via the Connections menu.
• 400 validation errors — the database schema changed in the UI; re-fetch with databases.retrieve and update property mappings.

Read references/mitigation.md for the full decision tree, token-rotation commands (AWS/GCP Secret Manager + kubect…

Notion Install & Auth

Overview

Set up the official Notion SDK and configure authentication for internal integrations. The Node.js SDK is @notionhq/client (npm) and the Python SDK is notion-client (pip) — both wrap the Notion API at https://api.notion.com/v1 using API version 2022-06-28.

Prerequisites

• Node.js 18+ or Python 3.8+
• Package manager (npm, pnpm, yarn, or pip)
• A Notion account (free or paid)
• Access to My Integrations dashboard

Instructions

Step 1: Create Integration and Install SDK

Create an internal integration at <https://www.notion.so/my-integrations>:

1. Click New integration
2. Name it, select the workspace, and choose capabilities (Read content, Update content, Insert content)
3. Copy the Internal Integration Secret (starts with ntn_ or secret_)

Install the SDK:

# Node.js / TypeScript (official SDK)
npm install @notionhq/client

# Python (official SDK)
pip install notion-client

Step 2: Configure Authentication

Store the token in environment variables -- never hardcode it:

# Set environment variable
export NOTION_TOKEN="ntn_your_integration_secret_here"

# Or add to .env file (add .env to .gitignore)
echo 'NOTION_TOKEN=ntn_your_integration_secret_here' >> .env

Share pages with your integration: In Notion, open the page or database you want to access. Click the ... menu, select Connections, and add your integration. Without this step, all API calls return object_not_found.

Step 3: Verify Connection

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const me = await notion.users.me({});
console.log(`Authenticated as: ${me.name} (${me.type})`);
console.log(`Bot ID: ${me.id}`);

If the bot user is returned, authentication is working.

Output

• SDK package installed (@notionhq/client for Node.js, notion-client for Python)
• Environment variable NOTION_TOKEN configured
• Integration connected to target pages/databases via Connections menu
• Verified API connectivity with users.me() call

Error Handling

Notion Known Pitfalls

Overview

The twelve most common mistakes when building Notion API integrations, each with the wrong pattern, why it fails, and the correct fix. These pitfalls account for the majority of developer support questions.

The lean flow lives here; the full wrong-vs-right code for every pitfall (TypeScript and Python) is in references/implementation.md.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN environment variable set
• Familiarity with Notion API concepts (databases, pages, blocks, properties)

Authentication

All calls authenticate with an internal integration token passed to the client constructor (new Client({ auth: process.env.NOTION_TOKEN }) / Client(auth=os.environ["NOTION_TOKEN"])). The token alone is not enough — every page and database must also be explicitly shared with the integration in the Notion UI (Pitfall #1). Never hardcode the token; read it from the environment.

Instructions

Work the pitfalls in order of frequency. Pitfall #1 is the single most common error, so it is worked in full below; #2–#12 follow the same wrong-vs-right shape and the complete code is in references/implementation.md.

Step 1: Not Sharing Pages with the Integration (Pitfall #1)

The single most common Notion API error. Every page/database must be explicitly shared with your integration. A 404 object_not_found does NOT mean the page is missing — it means your integration lacks access.

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

// This returns 404 even though the page EXISTS in your workspace
try {
  const page = await notion.pages.retrieve({ page_id: 'some-page-id' });
} catch (error) {
  if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) {
    // "object_not_found" does NOT mean the page doesn't exist
    // It means your integration doesn't have access
    console.error('Page exists but integration lacks access.');
    console.error('Fix: In Notion UI, open page -> ... menu -> Connections -> Add your integration');
    console.error('Tip: Share a parent page to grant access to ALL child pages');
  }
}

// Always verify access at startup
async function verifyAccess(databaseId: string): Promise<boolean> {
  try {
    await notion.databases.retrieve({ database_id: databaseId });
    return true;
  } catch {
    console.error(`Cannot access database ${databaseId…

Notion Load & Scale

Overview

Patterns for high-volume Notion API usage within the 3 requests/second rate limit. Covers parallel request orchestration with p-queue, worker queue architecture for background processing, full database pagination at scale (100K+ records), incremental sync using last_edited_time filters to avoid re-fetching unchanged data, and memory management for bulk operations via streaming and chunked processing.

Full runnable TypeScript + Python implementations for all three steps live in references/implementation.md; planning utilities live in references/examples.md.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• p-queue for rate-limited concurrency (npm install p-queue)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN set (each token gets its own 3 req/s limit)
• Test database in Notion (dedicated for load testing)

Authentication

All operations authenticate with a Notion internal integration token in the NOTION_TOKEN environment variable; the SDKs send it as a Bearer token automatically. Each token has an independent 3 req/s limit — the key lever for horizontal scaling. Full auth notes, including raw curl headers, are in references/implementation.md.

Instructions

The three patterns compose: rate-limited calls (Step 1) are the primitive the worker queue (Step 2) and the streaming paginator (Step 3) both build on. Read the lean summary here, then open references/implementation.md for the complete code.

Step 1: Parallel Requests Within Rate Limits

Notion enforces 3 requests/second per integration token. Drive every call through a single p-queue tuned to interval: 340 / intervalCap: 1 (~3/s with a safety margin) rather than relying on concurrency alone, and wrap each call so a rate_limited (429) response honors retry-after and retries once.

import PQueue from 'p-queue';

const apiQueue = new PQueue({ concurrency: 1, interval: 340, intervalCap: 1 });

// Every Notion call goes through this queue; add 429 retry inside (see refs).
const results = await Promise.all(
  dbIds.map(id => apiQueue.add(() =>
    notion.databases.query({ database_id: id, page_size: 100 })
  ))
);

Full wrapper (metrics, retry-after handling, Python token-bucket variant) is in Step 1 of references/implementation.md.

Step 2: Worker Que…

Notion Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Notion integrations. This skill creates a dedicated dev integration with its own token, structures the project for testability, mocks the Notion SDK in unit tests, and runs gated integration tests against a sandboxed dev workspace — so production data stays safe while you iterate quickly.

Prerequisites

• Completed notion-install-auth setup (you have a working Notion integration)
• Node.js 18+ with npm/pnpm, or Python 3.10+
• A Notion workspace where you can create test pages and databases

Authentication

This workflow uses a separate dev integration token, never the production token. The Notion SDK reads NOTION_TOKEN from the environment automatically. Store the dev token (prefix ntn_) in a git-ignored .env.development and commit a .env.example template so teammates know which variables to fill in. Token creation is covered by the notion-install-auth skill; Step 1 below wires it into the dev sandbox.

Instructions

Step 1: Create a Dev Integration and Workspace Sandbox

Create a separate integration exclusively for development so writes can never touch production data.

1. Go to Settings & Members > Connections > Develop or manage integrations (or visit developers.notion.com)
2. Click New integration and name it My App — Dev
3. Copy the token (starts with ntn_) into .env.development
4. Create a dedicated Dev Workspace page (or a top-level "Dev Testing" page) and share it with the dev integration
5. Inside that page, create test databases that mirror your production schema

# .env.development — git-ignored, dev only
NOTION_TOKEN=ntn_dev_xxxxxxxxxxxxxxxxxxxx
NOTION_TEST_DATABASE_ID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
NOTION_TEST_PAGE_ID=ffffffff-0000-1111-2222-333333333333

# .env.example — commit this as a template
NOTION_TOKEN=ntn_your_dev_token_here
NOTION_TEST_DATABASE_ID=your_test_db_id
NOTION_TEST_PAGE_ID=your_test_page_id

Recommended project layout — a notion/ module the app imports, and split unit/integration tests:

my-notion-project/
├── src/
│   ├── notion/
│   │   ├── client.ts          # Singleton with retry + rate-limit awareness
│   │   ├── queries.ts         # Database query wrappers
│   │   └── helpers.ts         # Property extractors, rich text builders
│   └── index.ts
├── tests/
│   ├── unit/
│   │   └── notion.test.ts     # Mocked SDK tests
│   └── integration/
│       └── notion.test.ts     # Live API tests (gated)
├── .env.development            # Dev token (git-igno…

Notion Migration Deep Dive

Overview

Production migration patterns for moving data to, from, and between Notion workspaces — rate-limited bulk import, paginated export, cross-platform conversion, and post-migration validation. Every bulk-write path respects Notion's 3 requests/second average rate limit.

Prerequisites

• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• p-queue for rate-limited concurrency (npm install p-queue)
• Source data access (CSV files, Confluence API, Google Docs API, etc.)
• Target Notion database(s) created with matching property schema

Authentication: create a Notion internal integration at notion.so/my-integrations, share the target database(s) with it, and export the secret as NOTION_TOKEN. Every code sample reads process.env.NOTION_TOKEN — the client never takes an inline credential.

Instructions

The workflow has three directions. Each step below gives the essential shape; the full runnable code lives in the reference files so this page stays scannable.

Step 1: Import CSV/JSON into a Notion database

Map each source field to a Notion property value object, strip properties the target schema does not have, and create pages through a rate-limited queue:

const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 3 }); // ≤3 req/s

await notion.pages.create({
  parent: { database_id: databaseId },
  properties: {
    Name: { title: [{ text: { content: record.name || 'Untitled' } }] },
    Status: { select: { name: record.status || 'Not Started' } },
  },
});

Validate the database schema with databases.retrieve before the loop so mismatched columns are dropped instead of failing every row. Full TypeScript + Python importers (property mapping, schema filtering, error collection): full walkthrough.

Step 2: Export from Notion to JSON/CSV

Page through databases.query (100 rows per page) and flatten each page's properties by type. Optionally pull block content for rich-content migrations:

do {
  const response = await notion.databases.query({
    database_id: databaseId, page_size: 100, start_cursor: cursor,
  });
  // extractProperties() maps title/select/multi_select/date/relation/... to flat values
  cursor = response.has_more ? response.next_cursor ?? undefined : undefined;
} while (cursor);

Full exporter with the per-property-type extractor and block-content reader: full w…

Notion Multi-Environment Setup

Overview

Configure separate Notion integrations for development, staging, and production. Each environment uses its own integration token, targets different databases, and applies environment-appropriate log levels and timeouts. This prevents dev data leaking into prod and enforces least-privilege per tier.

Prerequisites

• Notion workspace(s) per environment (one workspace can serve dev/staging via separate integrations)
• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• Secret management platform (AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault)
• CI/CD pipeline with per-environment variable injection

Instructions

The build has three steps. The lean skeleton below is enough to follow the workflow end to end; the full walkthrough carries the complete TypeScript and Python factories, every secret-manager command, and the CI/CD workflow.

Step 1: Per-environment integrations and an env-aware client

Create one integration per environment at <https://www.notion.so/my-integrations>, each with capabilities scoped to the tier — dev gets full access, prod gets the minimum required:

A single client factory reads NODE_ENV (or APP_ENV), pulls the token and database IDs from the environment, and applies the per-tier log level and timeout. It throws a descriptive error when NOTION_TOKEN is missing so misconfiguration fails loudly:

export function createNotionClient(): Client {
  const config = getConfig(); // reads NODE_ENV, token, per-tier defaults
  return new Client({
    auth: config.token,
    logLevel: config.logLevel,
    timeoutMs: config.timeoutMs,
  });
}

Full TypeScript getConfig/getDatabaseId and the Python equivalent: implementation.md, Step 1.

Step 2: Secret management and environment files

Keep dev/staging tokens in git-ignored per-environment files (.env.development, .env.staging). Never store production tokens in files — put them in a secret manager and inject…

Notion Observability

Overview

Instrument Notion API calls with metrics, structured logging, and alerting. Track request rates, latencies, error rates, and rate limit headroom across a full observability stack: an instrumented client wrapper, Prometheus metrics, structured logging via pino, health check endpoints, and alerting rules.

Prerequisites

• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• Prometheus-compatible metrics backend (optional: Grafana, Datadog, or CloudWatch)
• Structured logging library: pino (Node.js) or structlog (Python)

Authentication

All snippets read the integration token from the NOTION_TOKEN environment variable (never hard-code it) and pass it as auth to the Notion client constructor. Store it in your secret manager and inject it at runtime. The health check and metrics endpoints below expose no secrets — only aggregate counters and status.

Instructions

The workflow layers three pieces. Build them in order; each is self-contained. Full code for every step lives in references/implementation.md.

Step 1: Instrumented client wrapper

Wrap every Notion call so timing, error classification, rate-limit detection, and structured logging happen automatically. The wrapper accumulates per-operation latency buckets and exposes getMetrics() for avg/p95. Skeleton:

class InstrumentedNotionClient {
  async call<T>(operation: string, fn: (c: Client) => Promise<T>): Promise<T> {
    const start = performance.now();
    try {
      const result = await fn(this.client);
      this.recordLatency(operation, Math.round(performance.now() - start));
      return result;
    } catch (error) {
      if (isNotionClientError(error) && error.code === APIErrorCode.RateLimited) {
        this.metrics.rateLimitCount++;
      }
      throw error;
    }
  }
}

A Python (notion-client) equivalent is in the reference. Full TypeScript + Python wrappers: references/implementation.md (Step 1).

Step 2: Prometheus metrics export

Register a request counter, a latency histogram (buckets tuned for Notion's typical 200-800ms responses), an error counter keyed by error code, and a rate-limit gauge. Wrap calls with startTimer() and expose a /metrics endpoint for scraping. Full export code: references/implementation.md (Step 2).

Step 3: Health check, structured logging, and alerting

Add a /health/notion endpoint that probes users.me and returns 200…

Notion Performance Tuning

Overview

Optimize Notion API performance by minimizing API calls, caching responses with TTL-based invalidation, batching block appends, parallelizing requests within rate limits, selecting only needed properties, and implementing incremental sync patterns. Target latency benchmarks: Database Query p50=150ms, Page Create p50=200ms, Search p50=300ms.

Prerequisites

• @notionhq/client installed (npm install @notionhq/client)
• p-queue for rate-limited parallelism (npm install p-queue)
• lru-cache for TTL-based caching (npm install lru-cache)
• Authentication: a Notion integration token in NOTION_TOKEN (internal integration secret from <https://www.notion.so/my-integrations>), passed as new Client({ auth: process.env.NOTION_TOKEN })
• Understanding of your access patterns (read-heavy vs write-heavy)
• Optional: Redis or ioredis for distributed caching across instances

Instructions

Apply the three techniques in order — each builds on the previous one. The lean skeletons below are enough to follow the workflow; drill into the linked reference files for the complete, copy-paste-ready code.

Step 1: Minimize API Calls and Reduce Payload

Avoid N+1 patterns, page with page_size: 100 (the maximum), select only the properties you need with filter_properties, and batch block appends in chunks of 100.

// Batch block appends — up to 100 blocks per request (API maximum)
for (let i = 0; i < blocks.length; i += 100) {
  await notion.blocks.children.append({
    block_id: pageId,
    children: blocks.slice(i, i + 100),
  });
}

See full implementation walkthrough for the N+1-vs-batched query comparison, filter_properties usage, and selective block-tree expansion.

Step 2: Cache Responses with TTL-Based Invalidation

Use an LRU cache with per-operation TTLs (short for volatile data like search, longer for stable data like schemas) and invalidate entries on every write to keep reads consistent.

import { LRUCache } from 'lru-cache';
const cache = new LRUCache<string, any>({ max: 1000, ttl: 60_000, allowStale: false });
// Invalidate on write: for (const key of cache.keys())
//   if (key.startsWith(`db:${dbId}:`)) cache.delete(key);

See full implementation walkthrough for tiered TTL configuration, cursor-based cached pagination, write-through invalidation, and cache-stats monitoring.

Step 3: Parallel Requests with Rate-Limited Queue and Latency Monitoring

See parallel …

Notion Policy & Guardrails

Overview

Governance framework for Notion integrations at scale. Covers integration naming standards, page sharing policy enforcement, property naming conventions, database schema validation, and access audit scripts. Uses Client from @notionhq/client for programmatic enforcement.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN environment variable set (admin-level integration recommended for audits)
• CI/CD pipeline (GitHub Actions examples provided)

Authentication

All scripts authenticate with a Notion internal integration token read from the NOTION_TOKEN environment variable — never hardcode it. Create the token at notion.so/my-integrations, share the target pages/databases with the integration, and inject the token via CI secrets (e.g. secrets.NOTION_AUDIT_TOKEN). Audit scripts want a broadly-shared admin integration; runtime bots want the narrowest sharing scope that works. Token rotation is tracked in Step 1 (max 90 days).

Instructions

The workflow has three stages. Each stage's full enforcement code (TypeScript + Python) lives in references/implementation.md — the skeletons below show the shape; drill into the reference for the complete functions.

Step 1: Integration Naming Standards and Token Management

Establish a {team}-{env}-{purpose} naming convention (e.g. eng-prod-sync) so teams can identify which bot accessed what, validate it at startup, and track token rotation (max 90 days). Core check:

// Must match: /^[a-z]+-[a-z]+-[a-z]+$/  →  eng-prod-sync
function validateIntegrationName(name: string): string[] { /* ... */ }

Full IntegrationConfig, startup validation, and checkTokenExpiry registry: references/implementation.md § Step 1.

Step 2: Page Sharing Policies and Property Naming Conventions

Standardize property names across databases (PascalCase titles, Date/At suffixes on dates, plural multi-selects, a banned-name list) and audit which pages are shared publicly. Core check:

async function auditDatabaseSchema(notion, databaseId):
  Promise<{ violations: string[]; recommendations: string[] }> { /* ... */ }

Full PROPERTY_NAMING_RULES, auditPageAccess, and the Python port: references/implementation.md § Step 2.

Step 3: Access Audit Scripts and Database Schema Standards

R…

Notion API Production Deployment Checklist

Overview

A structured 12-section checklist for deploying Notion API integrations to production, covering authentication security, capability scoping, page sharing, rate limits, pagination, error handling, versioning, retries, monitoring, graceful degradation, data validation, and OAuth token lifecycle. Each section maps to a specific failure mode seen in production Notion integrations, and every item is testable — the skill produces a verified pass/fail report, not aspirational guidance.

Prerequisites

• Node.js 18+ with @notionhq/client v2.x installed
• Working Notion integration tested in a development workspace
• Production Notion API token (internal) or OAuth credentials (public integration)
• Target databases and pages identified by ID
• Deployment platform configured (Vercel, Railway, AWS, etc.)

Verify SDK is installed:

node -e "const { Client } = require('@notionhq/client'); console.log('SDK loaded')" 2>/dev/null \
  || echo "MISSING: npm install @notionhq/client"

Instructions

Work through the checklist in order, marking each item pass or fail. A single fail in sections 1-6 is a deployment blocker.

1. Run the pre-deploy smoke test (see Examples) to confirm the token is set, auth works, and target databases are reachable. This catches the most common failure — a page that is not shared with the integration — before you go deeper.
2. Grade each of the 12 sections against its checkbox items. The summary table below is the map; the full item-by-item detail, fail criteria, and code snippets live in references/checklist-sections.md.
3. Pull implementation patterns (rate-limited queue, paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange) from references/code-examples.md as each section requires them.
4. Record a pass/fail per section and total the blocking (1-6) vs non-blocking (7-12) failures.
5. Emit the readiness report (see Output) with the final verdict: ready to deploy, or blocked with the count of items to fix.

The 12 sections at a glance

Notion Rate Limits

Overview

The Notion API enforces 3 requests per second per integration token across all endpoints and tiers. Exceeding this returns HTTP 429 with a Retry-After header. Detect with isNotionClientError() + APIErrorCode.RateLimited, implement exponential backoff with jitter, and use queue-based throttling for high-throughput workloads.

Prerequisites

• @notionhq/client v2.x (TypeScript) or notion-client (Python)
• Integration token in NOTION_TOKEN from notion.so/my-integrations
• For queue patterns: p-queue v8+ (npm install p-queue)

Instructions

Step 1 — Detect Rate Limits and Apply Exponential Backoff

The SDK retries 429 automatically (2 retries, 3 total attempts). For heavier workloads, use custom backoff that honors Retry-After and adds jitter to prevent thundering herd:

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function withBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5, baseMs = 1000, maxMs = 32_000
): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try { return await fn(); }
    catch (err) {
      if (i === maxRetries) throw err;
      if (isNotionClientError(err) && err.code === APIErrorCode.RateLimited) {
        const wait = parseInt((err as any).headers?.['retry-after'] ?? '1', 10);
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }
      if (isNotionClientError(err) && err.status && err.status < 500) throw err;
      const delay = Math.min(baseMs * 2 ** i + Math.random() * 500, maxMs);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Exhausted retries');
}

Step 2 — Throttle with Queue-Based Request Management

Enforce the 3 req/s limit at the application level instead of relying on 429 responses:

import PQueue from 'p-queue';

const queue = new PQueue({
  concurrency: 3, interval: 1000, intervalCap: 3,
  carryoverConcurrencyCount: true,
});

async func…

Notion Reference Architecture

Overview

Production-grade architecture for Notion integrations using @notionhq/client. This skill defines a four-layer architecture — client singleton, repository pattern, service layer, and caching — that scales from simple scripts to enterprise applications, with multi-integration setups, event-driven processing, and testing strategies.

Notion API version: 2022-06-28 | Rate limit: 3 requests/second per integration | Max page size: 100

Prerequisites

• Node.js 18+ with TypeScript strict mode enabled
• @notionhq/client v2.x installed (npm install @notionhq/client)
• A Notion internal integration created at <https://www.notion.so/my-integrations>
• NOTION_TOKEN environment variable set with the integration token
• Target databases/pages shared with the integration via "Add connections"

Instructions

Build the architecture in four layers, bottom-up. Each layer depends only on the ones below it, so wire them in order. The full copy-ready code for every layer lives in the implementation reference — scaffold the project layout first, then follow the steps below.

Step 1: Client singleton with retry and rate limiting

Wrap @notionhq/client in a singleton with explicit rate limiting (Notion caps at 3 req/s per integration) and exponential-backoff retry. Expose separate reader and writer clients so a read-heavy and a write-scoped integration can run side by side and double effective throughput.

// src/notion/client.ts — skeleton (full code in the implementation reference)
export function getReaderClient(): Client { /* singleton, NOTION_READER_TOKEN ?? NOTION_TOKEN */ }
export function getWriterClient(): Client { /* singleton, NOTION_WRITER_TOKEN ?? NOTION_TOKEN */ }
export async function rateLimitedCall<T>(fn: () => Promise<T>): Promise<T> { /* 3 req/s window */ }
export async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> { /* backoff */ }

See the full singleton, rate limiter, and retry wrapper in the implementation reference (Step 1).

Step 2: Repository and service layers

The repository layer wraps raw Notion API calls with pagination (Notion caps at 100 results per request), type extraction, and error handling. The service layer sits above it with business logic, schema validation, and cache-aware operations. Keep API shape in the repository and domain rules in the service so each is independently testable.

// Layer boundary — full classes in the implement…

Notion Reliability Patterns

Overview

Production reliability patterns for Notion integrations: retry with exponential backoff, a circuit breaker to prevent cascade failures, and graceful degradation (offline cache, health checks, fallback content) so users see stale data instead of errors when the API is unreachable. All patterns use Client from @notionhq/client and handle Notion-specific error codes.

The three layers compose in order — retry sits inside the circuit breaker, which sits inside the cache/fallback layer. Read the skeletons below to follow the workflow, then open references/implementation.md for the complete copy-paste code.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• lru-cache for in-memory caching (npm install lru-cache)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN environment variable set
• Understanding of circuit breaker and retry patterns

Authentication

All patterns authenticate with a Notion internal integration token read from the NOTION_TOKEN environment variable — new Client({ auth: process.env.NOTION_TOKEN }) (TS) or Client(auth=os.environ["NOTION_TOKEN"]) (Python). Never hardcode the token; the health check calls notion.users.me() to confirm the token is valid and the API reachable.

Instructions

Build the three layers in order. Each skeleton shows the shape; the full implementation lives in references/implementation.md.

Step 1: Retry with Exponential Backoff

Classify errors as transient (429, 500, 502, 503, timeouts, network) vs permanent (400/401/404), retry only the transient ones with exponential backoff + jitter, and honor the Retry-After header on rate limits.

async function retryWithBackoff<T>(fn: () => Promise<T>, opts = {}): Promise<T> {
  // maxRetries=4, baseDelayMs=1000. Loop; on transient error wait
  // baseDelayMs * 2^attempt (+ jitter), else rethrow. See implementation.md.
}

Full code (TypeScript + Python, including isTransientError and rate-limit handling): references/implementation.md Step 1.

Step 2: Circuit Breaker to Prevent Cascade Failures

During a sustained outage, stop hammering the API and fail fast. The breaker moves closed → open after N consecutive transient failures, waits a reset timeout, then tests recovery in half-open before returning to closed.

class NotionCircuitBreaker {
  // failure…

Notion SDK Patterns

Overview

Production-ready patterns for the official Notion SDK (@notionhq/client for TypeScript, notion-client for Python) covering client initialization, database queries with filters and sorts, cursor-based pagination, rich text construction, block manipulation, and type-safe error handling using SDK error codes.

The full workflow lives in three steps below. Each step shows the essential skeleton inline; deep variants (compound filters, generic pagination helpers, block manipulation, exhaustive error switches) are in references/patterns.md, and copy-paste task recipes are in references/examples.md.

Prerequisites

• Node.js 18+ with @notionhq/client v2.x installed, or Python 3.9+ with notion-client
• A Notion integration token (NOTION_TOKEN) from notion.so/my-integrations
• Target databases/pages shared with the integration (Share > Invite > select your integration)
• TypeScript 5+ with strict mode enabled (for TypeScript patterns)

Instructions

Step 1 — Initialize the Client and Query Databases

Set up the SDK client and execute a filtered, sorted database query.

TypeScript:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const response = await notion.databases.query({
  database_id,
  filter: {
    property: 'Status',
    select: { equals: 'Active' },
  },
  sorts: [{ property: 'Created', direction: 'descending' }],
});

Python:

from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

results = notion.databases.query(
    database_id=db_id,
    filter={"property": "Status", "select": {"equals": "Active"}},
    sorts=[{"property": "Created", "direction": "descending"}],
)

For and/or compound filters and multi-key sorts, see the Compound Filters section of references/patterns.md.

Step 2 — Paginate Results and Manipulate Blocks

The Notion API returns at most 100 results per request. Loop on the cursor to retrieve every record:

let cursor: string | undefined;
do {
  const { results, next_cursor, has_more } = await notion.databases.query({
    database_id,
    start_cursor: cursor,
  });
  for (const page of results) {
    console.log(page.id);
  }
  cursor = has_more && next_cursor ? next_cursor : un…

Notion Search & Data Retrieval

Overview

Search across a Notion workspace, query databases with compound filters, retrieve individual pages, and extract nested block content. Covers the full read path: workspace-level search, database queries with filter/sort/pagination, page retrieval, and recursive block tree traversal.

Prerequisites

• @notionhq/client installed (npm install @notionhq/client)
• Notion integration token with read access to target pages/databases
• Integration added to target pages via the Share menu in Notion
• Completed notion-install-auth setup

Instructions

Step 1: Search the Workspace

Call notion.search() to find pages and databases. The integration only sees content explicitly shared with it.

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Search for pages matching a query
const searchResults = await notion.search({
  query: 'meeting notes',
  filter: {
    property: 'object',
    value: 'page',        // 'page' or 'database'
  },
  sort: {
    direction: 'descending',
    timestamp: 'last_edited_time',
  },
  page_size: 20,
});

for (const result of searchResults.results) {
  if (result.object === 'page' && 'properties' in result) {
    const titleProp = Object.values(result.properties)
      .find(p => p.type === 'title');
    const title = titleProp?.type === 'title'
      ? titleProp.title.map(t => t.plain_text).join('')
      : 'Untitled';
    console.log(`${title} (${result.id})`);
  }
}

An empty query string returns all shared content. Results are eventually consistent — newly shared pages may take a few seconds to appear in the index.

Step 2: Query Databases with Filters

Call notion.databases.query() for structured queries. Filters support compound and/or logic. See filter-operators.md for every property type and operator.

// Single filter
const activeItems = await notion.databases.query({
  database_id: 'your-database-id',
  filter: {
    property: 'Status',
    select: { equals: 'Active' },
  },
  sorts: [
    { property: 'Priority', direction: 'descending' },
  ],
  page_size: 50,
});

// Compound filter with AND
const highPriorityActive = await notion.databases.query({
  database_id: 'your-database-id',
  filter: {
    and: [
      { property: 'Status', select: { equals: 'Active' } },
      { property: 'Priority', number: { greater_than: 3 } },
    ],
  },
});

Step 3: Paginate, Retri…

Notion Security Basics

Overview

Security fundamentals for the Notion API: integration token management, internal vs public integration models, principle of least privilege for capabilities, page-level access auditing, token rotation, OAuth2 flows for public integrations, and webhook verification. All examples use @notionhq/client v2.x and target the 2022-06-28 API version.

This SKILL.md gives you the workflow at a high level with the essential skeletons inline. Drill into the linked references for the full code:

• Token storage, secret scanning, and access auditing — Step 1 + Step 2 in full
• Token rotation, OAuth2, and webhook verification — Step 3 in full
• Worked examples — dual-integration .env + startup validation script

Prerequisites

• Notion integration created at notion.so/my-integrations
• Node.js 18+ with @notionhq/client installed (npm install @notionhq/client)
• Understanding of environment variables and .env file patterns
• For public integrations: OAuth2 client ID and secret from the integration dashboard

Instructions

Step 1: Secure Token Storage and .env Management

Integration tokens are secrets with the same sensitivity as database passwords. Notion tokens use the ntn_ prefix (current) or secret_ prefix (legacy). Both grant full access to every page shared with the integration. Two rules: never hardcode a token, and gitignore every .env variant BEFORE creating one.

Load from the environment and validate the token format before use:

import { Client } from '@notionhq/client';

const token = process.env.NOTION_TOKEN;
if (!token) throw new Error('NOTION_TOKEN is required (see notion.so/my-integrations).');
if (!token.startsWith('ntn_') && !token.startsWith('secret_')) {
  throw new Error('NOTION_TOKEN has an unexpected format (expected ntn_ or legacy secret_).');
}

const notion = new Client({ auth: token });

Add a CI secret-scan step (grep -rE "(ntn_|secret_)[a-zA-Z0-9]{30,}") so an accidentally committed token fails the build. Full .gitignore patterns, the .env.example template, and the complete GitHub Actions workflow are in token storage, secret scanning, and access auditing.

Step 2: Least-Privilege Capabilities and Access Auditing

Configure integration capabilities at the integration dashboard. Each integration should requ…

Notion Upgrade & Migration

Overview

Step-by-step guide for upgrading @notionhq/client (Node.js) and notion-client (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version 2022-06-28 and the SDK feature timeline through v2.x.

The workflow is three phases — audit what you run today, upgrade on an isolated branch while fixing breaking changes, then verify every API surface before merging. Deep code (the full breaking-change catalog, the verification suite, and worked recipes) lives in references/ so this file stays a scannable playbook.

Prerequisites

• Existing project with @notionhq/client or notion-client installed
• Git repository with clean working tree (no uncommitted changes)
• Test suite covering Notion API calls (or willingness to add verification tests)
• NOTION_TOKEN environment variable configured

Instructions

Step 1: Audit Current Versions and API Surface

Determine what you are running today before changing anything.

# Node.js — installed vs latest SDK version
npm ls @notionhq/client
npm view @notionhq/client version

# Python — installed vs latest SDK version
pip show notion-client 2>/dev/null | grep Version
pip index versions notion-client 2>/dev/null | head -1

# Find which API version your code specifies
grep -rn "notionVersion\|Notion-Version\|notion_version" src/ lib/ app/ 2>/dev/null

Record the current SDK version and API version before proceeding. If no notionVersion is set explicitly, the SDK uses its built-in default (typically 2022-06-28 for current releases).

SDK version history — key milestones:

API version timeline:

Notion Webhooks & Event Handling

Overview

Notion offers three approaches to change detection, each with different trade-offs:

Honest assessment: Notion's native webhook support arrived in mid-2025 and covers page, database, comment, and data source events. It works well for event notification but does not deliver full payloads — you still need API calls to fetch the changed data. For many use cases, especially incremental sync and backup, polling with last_edited_time filters remains the most battle-tested pattern.

Prerequisites

• @notionhq/client v2.3+ installed (npm install @notionhq/client)
• Notion integration created at <https://www.notion.so/my-integrations>
• Integration shared with target pages/databases (Connections menu in Notion)
• NOTION_TOKEN environment variable set to the integration's Internal Integration Secret
• For native webhooks: HTTPS endpoint accessible from the internet

Authentication

All API calls authenticate with the integration's Internal Integration Secret, passed as a bearer token. The @notionhq/client handles the header when you construct the client — never hardcode the secret:

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Store NOTION_TOKEN in your environment (.env, a GitHub Actions secret, or a secrets manager) and grant the integration access to each target page/database via the Connections menu.

Webhook deliveries themselves carry no bearer token — verify them with the url_verification handshake and treat the payload as untrusted, fetching the real data through the authenticated client rather than trusting the event body.

Instructions

Pick an approach from the Overview table, then follow the matching step. Steps 1 and 2 keep a runnable skeleton here and link to the full implementation in references/.

Step 1: Polling-Based Change Detection

Polling is the most reliable approach and works with every Notion API version. Use notion.search() to discover recently edited content across the entire workspace, or not…