Notion Connector

Notion connector — Notion as a code-backed ops store

Wire server code to the Notion HTTP API so a database behaves like a small operational store: push rows, pull rows, sync both ways idempotently, read and write page blocks. This skill owns the outbound Notion API surface only — the database/data-source data model, property-type write shapes, and the rate-limit/pagination discipline that the API forces on you.

Route elsewhere

Setup (4 steps)

1. Create an internal integration in Notion → Settings → Integrations. Copy the secret — it looks like ntn_... (older ones secret_...).
2. Put the token in an env var, never in client-side JS, never committed. It is a bearer secret; treat it like a password. See ../secure-coding/SKILL.md.
3. Share the target database/page with the integration in the Notion UI (the page ••• menu → Connections). Skip this and every call 404s or returns empty — the integration sees nothing it was not explicitly granted.
4. Construct the SDK client with a pinned Notion-Version. Official JS SDK is @notionhq/client v5.12.0+ (latest 5.22.0, 2026-05-19); its default notionVersion is the current major 2025-09-03, and it supports the latest 2026-03-11 if you opt in. The default and method names below are stable across the whole 5.x line. Behavior differs across versions, so pin it per client (or per request) — an unpinned client drifts when the default moves.

import { Client } from "@notionhq/client"; // v5.12.0+ (latest 5.22.0)

const notion = new Client({
  auth: process.env.NOTION_TOKEN,          // ntn_... — env only, never inlined
  notionVersion: "2025-09-03",             // pin it; do not ride the default
});

The database → data source model (biggest gotcha)

Post 2025-09-03 a database is a container of one or more data sources, not a queryable table: it holds a data_sources array and each data source has its own schema. Resolve the data source before you query — query and read schema against it, not against the database, or code that worked last year 404s silently.

Endpoints moved to /v1/data_sources:

- POST /v1/databases/:database_id/query        # 2022-06-28 — 404s on 2025-09-03+
+ POST /v1/data_sources/:data_source_id/query  # query rows
+ GET  /v1/data_sources/:data_source_id         # schema (properties)
+ PATCH /v1/data_sources/:data_source_id        # update schema / title

// Resolve once, then reuse the data_source_id everywhere downstream.
const db = await notion.databases.retrieve({ database_id: DATABASE_ID });
const dataSourceId = db.data_sources[0].id; // verify by name if >1 exists

Query a data source

Send filter + sorts in the body. Page size maxes at 100; results are cursor-based. Always loop on has_more + next_cursor or you silently drop every row past the first 100. Filter operand shapes per property type live in references/property-shapes.md.

async function queryAll(dataSourceId: string, filter?: object) {
  const rows: any[] = [];
  let cursor: string | undefined = undefined;
  do {
    const res = await notion.dataSources.query({
      data_source_id: dataSourceId,
      filter,
      page_size: 100,                 // hard max
      start_cursor: cursor,
    });
    rows.push(...res.results);
    cursor = res.has_more ? res.next_cursor ?? undefined : undefined;
  } while (cursor);
  return rows;
}

Property write shapes

Most write failures (HTTP 400) are a wrong property envelope. Each type has its own JSON shape. The high-frequency ones:

Full write + read-parse JSON for every type → references/property-shapes.md.

Create / update pages (rows)

A page's parent is the data source, not the database:

// CREATE a row
await notion.pages.create({
  parent: { type: "data_source_id", data_source_id: dataSourceId },
  properties: {
    Name: { title: [{ text: { content: "Ship invoice export" } }] },
    Status: { status: { name: "In progress" } },
    ExternalId: { rich_text: [{ text: { content: extId } }] },
  },
});

// UPDATE a row: PATCH the page by id; send only changed properties
await notion.pages.update({
  page_id,
  properties: { Status: { status: { name: "Done" } } },
});

To soft-delete: on 2025-09-03 set { archived: true }; on 2026-03-11 that field is renamed { in_trash: true }. Match the field to the version you pinned (see references/api-versions.md).

Sync patterns

Idempotency is the whole game. Store the Notion page_id keyed by your external id (a column in your DB, or a rich_text "ExternalId" property in Notion). An upsert is: query-by-external-key → if a row exists, pages.update; else pages.create. Never blind-create on a re-run — that is how you get duplicate rows.

• One-way (app → Notion): upsert on every sync; the app is source of truth.
• Two-way: track a last_edited_time watermark on each side; last-writer wins, or flag conflicts for review. Cursor-checkpoint large pulls.

Dedupe, two-way reconcile, and checkpointing → references/sync-patterns.md.

Rate limits & resilience

The integration is capped at ~3 requests/second average. Over-limit calls return HTTP 429 with a Retry-After header (seconds) — honor it, do not guess a fixed sleep. Cap concurrency, batch reads, back off on 429.

async function withRetry<T>(fn: () => Promise<T>, tries = 5): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (e: any) {
      const after = Number(e?.headers?.["retry-after"]);
      if (e?.status === 429 && i < tries) {
        const wait = Number.isFinite(after) ? after * 1000 : 2 ** i * 500;
        await new Promise((r) => setTimeout(r, wait));
        continue;
      }
      throw e;
    }
  }
}

Version migration

Exact field/endpoint diffs → references/api-versions.md.

Anti-patterns

verify.sh

scripts/verify.sh <file-or-dir> statically lints a connector you (or the agent) wrote: it flags a missing pinned Notion-Version/notionVersion, a deprecated databases/:id/query query path, a query without a has_more/next_cursor loop, and missing 429/Retry-After handling. Read-only; exits 0 on a clean or empty target. It does not call Notion.