Skip to content

ericrisco/rsc-harness / skills/notion-connector

notion-connector

Verified

Use when wiring server code or a cron job to Notion as an ops backend over its HTTP API: pushing or mirroring database rows, two-way sync without duplicates, page blocks, or an integration broken by the 2025-09-03 data-source split. NOT generic REST wiring (that is `api-connector-builder`), NOT inbound Notion webhook events (that is `webhooks`).

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

SituationRoute to
Generic "call any REST API", nothing Notion-specific../api-connector-builder/SKILL.md
Receiving + verifying inbound Notion webhook events../webhooks/SKILL.md
Notion is one node in a multi-tool sequence../automation-flows/SKILL.md
CSV/tabular bulk transforms, column mechanics../spreadsheet-ops/SKILL.md
Token handling, secret rotation, never-client-side rules../security-audit/SKILL.md

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 ../security-audit/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.

You have…Do this
A database_idGET /v1/databases/:id → read data_sources[] ({id,name}) → use that id
Already a data_source_idUse it directly for query/schema/pages
A DB with >1 data sourcePick the right one by name; never assume index 0

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:

TypeWrite shape (abridged)
title{ title: [{ text: { content } }] }
rich_text{ rich_text: [{ text: { content } }] }
number{ number: 42 }
select{ select: { name } }
multi_select{ multi_select: [{ name }] }
status{ status: { name } }
date{ date: { start, end? } } (ISO 8601)
checkbox{ checkbox: true }
relation{ relation: [{ id }] }
people{ people: [{ id }] }
url{ url: "https://…" }

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

From → ToWhat changed
2022-06-28 → 2025-09-03DB is a container; query/schema move to /v1/data_sources; page parent is data_source_id; search filter value "database" → "data_source"
2025-09-03 → 2026-03-11block after param → position object (after_block/start/end); archived → in_trash (pages/dbs/blocks/data sources); block type transcription → meeting_notes

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

Anti-patterns

Anti-patternWhy it bitesDo instead
Unpinned Notion-VersionBehavior shifts when the default movesPin per request/client
POST /v1/databases/:id/query on 2025-09-03+404 — that path is goneResolve data source → /v1/data_sources/:id/query
Forgetting to share the DB with the integration404 / empty results, looks like an auth bugShare in the UI (step 3)
No pagination loopSilently drops every row past 100Loop on has_more + next_cursor
Ignoring 429 / fixed sleepHammers the 3 req/s ceiling, gets bannedHonor Retry-After, exponential backoff
Blind pages.create on every syncDuplicate rows on re-runUpsert: query-by-external-key first
Token in client-side JS or committedLeaked bearer secret = full workspace accessEnv var + secret manager
Assuming one DB = one schemaBreaks on multi-data-source DBsResolve and select by data-source name
Using database_id as a page parentRejected on 2025-09-03+{ type: "data_source_id", data_source_id }
archived on 2026-03-11Field renamedUse in_trash for that version

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.

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall