Notion - Opus Transcript

{
  "description": "Fetch Notion docs and specs",
  "prompt": "Research Notion's API capabilities for managing structured data and content. Fetch the following resources and compile findings:\n\n1. Fetch https://developers.notion.com/llms.txt (or llms-full.txt) - machine-readable docs\n2. Fetch https://developers.notion.com/docs - main API documentation overview\n3. Fetch https://developers.notion.com/reference - API reference\n4. Fetch https://www.notion.so/help/guides - for product capabilities\n5. Check https://github.com/makenotion for official SDKs, MCP servers, CLI tools\n6. Fetch https://developers.notion.com/openapi.json or similar OpenAPI spec if available\n\nFor each resource, extract:\n- Key API concepts (pages, databases, blocks, properties, etc.)\n- What structured data operations are supported (CRUD on databases, filtering, sorting, property types)\n- What content/block types are supported (headings, lists, code blocks, etc.)\n- Any gaps between what the product UI can do vs what the API can do\n- Any agent-oriented interfaces (MCP server, CLI, SDK)\n- Rate limits and authentication model\n- Any limitations or gotchas\n\nBe thorough - read the actual content of pages rather than just listing URLs. Compile a comprehensive summary.",
  "subagent_type": "general-purpose"
}

Research complete. Here is a summary of findings, with the full detailed report written to `/Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/research/notion-api-capabilities.md`.

---

## Key Findings

### API Architecture
- RESTful API at `https://api.notion.com`, current version `2026-03-11`.
- Core objects: **Pages**, **Data Sources** (evolved from Databases in API v2025-09-03), **Blocks** (34 types), **Users**, **Comments**, **File Uploads**.
- New Markdown endpoints (`GET/PATCH /v1/pages/:id/markdown`) allow reading and writing page content as Notion-flavored Markdown -- a significant improvement for agent workflows.

### Structured Data Operations
- **20 database property types** with full CRUD on most (Title, Rich Text, Number, Select, Multi-select, Date, Checkbox, URL, Email, Phone, Files, People, Relation). Formula and Rollup are read-only.
- **Compound filters** (and/or, nestable) with property-type-specific operators. Sorts on any property or timestamps.
- **Pagination**: cursor-based, max 100 items per page.
- **Cannot create Status properties** via API (can only read/write values on existing ones).

### Content/Block Types
- 34 block types documented. Most are fully creatable (paragraphs, headings, lists, to-dos, code, images, tables, callouts, toggles, etc.).
- Read-only blocks: Link Preview, Meeting Notes.
- UI-only blocks returned as `"unsupported"`: Forms, Buttons, some automation blocks.

### Major UI-vs-API Gaps
- **No database view management** (table, board, timeline, calendar, chart, gallery views cannot be created/read/managed via API).
- **No linked databases or wiki databases** via API.
- **Title-only search** (no full-text content search).
- **No automations, forms, buttons, charts, AI features, page analytics, or permissions management** via API.
- **No Notion Mail or Notion Calendar** API access.

### Rate Limits
- **3 requests/second average** (quite restrictive). HTTP 429 with `Retry-After` header.
- 500KB max request body, 1000 blocks max per request, 100 blocks per append, rich text capped at 2,000 chars.
- File URLs expire after 1 hour.

### Agent Interfaces
- **Official MCP Server** (`@notionhq/notion-mcp-server`): 22 tools for AI agents, supports STDIO and HTTP transport. Deprecation warning -- Notion is shifting to a remote MCP server.
- **Official JS/TypeScript SDK** (`@notionhq/client`): Full API coverage, auto-retry, pagination utilities, type-safe.
- **No official CLI tool** found.
- **Notion Custom Agents**: Built-in product feature where agents connect to external tools via MCP; integrates with Cursor IDE.

### Authentication
- Internal integrations: static token (`ntn_****`), pages must be explicitly shared.
- Public integrations: OAuth 2.0 with refresh tokens (`nrt_****`).
- Key constraint: integration access is page-by-page, not workspace-wide.

### Critical Gotchas
1. The 25-reference limit on relations in formulas/rollups can silently produce wrong results.
2. Template application is async -- pages return blank, requiring polling or webhooks.
3. The data source vs database split (v2025-09-03) is a breaking change requiring migration from `database_id` to `data_source_id`.
4. No bulk operations -- each page is a separate API call at 3 req/sec.
5. `table_width` and synced block content are immutable after creation.
agentId: a79d53ccaeab62537 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 32474
tool_uses: 20
duration_ms: 265555</usage>

{
  "command": "ls /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/",
  "description": "List current project directory"
}

RUN-CHECKLIST.md
model-id.txt
prompts
research

{
  "command": "npm init -y 2>&1 | tail -5",
  "description": "Initialize npm project"
}

  "license": "ISC",
  "type": "commonjs"
}

{
  "command": "npm install @notionhq/client 2>&1 | tail -3",
  "description": "Install official Notion SDK"
}

npm error To permanently fix this problem, please run:
npm error   sudo chown -R 501:20 "/Users/mattsteen/.npm"
npm error A complete log of this run can be found in: /Users/mattsteen/.npm/_logs/2026-03-13T12_42_25_868Z-debug-0.log

{
  "command": "npm install @notionhq/client 2>&1 | tail -5",
  "description": "Retry Notion SDK install",
  "dangerouslyDisableSandbox": true
}

added 1 package, and audited 2 packages in 1s

found 0 vulnerabilities

{
  "file_path": "/Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.env.example",
  "content": "NOTION_TOKEN=ntn_[REDACTED]_TOKEN_HERE\nNOTION_TEST_PAGE_ID=YOUR_PAGE_ID_HERE\n"
}

File created successfully at: /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.env.example

{
  "file_path": "/Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.gitignore",
  "content": "node_modules/\n.env\n"
}

File created successfully at: /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.gitignore

{
  "file_path": "/Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/scripts/verify-connection.mjs",
  "content": "/**\n * Verify Notion API connection.\n * Usage: NOTION_TOKEN=ntn_... NOTION_TEST_PAGE_ID=... node scripts/verify-connection.mjs\n */\nimport { Client } from \"@notionhq/client\";\n\nconst token = process.env.NOTION_TOKEN;\nconst pageId = process.env.NOTION_TEST_PAGE_ID;\n\nif (!token || !pageId) {\n  console.error(\"Set NOTION_TOKEN and NOTION_TEST_PAGE_ID env vars\");\n  process.exit(1);\n}\n\nconst notion = new Client({ auth: token });\n\n// 1. Verify auth by fetching bot user info\nconst me = await notion.users.me({});\nconsole.log(`✓ Authenticated as: ${me.name} (${me.type})`);\n\n// 2. Verify page access\nconst page = await notion.pages.retrieve({ page_id: pageId });\nconst title =\n  page.properties?.title?.title?.[0]?.plain_text ??\n  page.properties?.Name?.title?.[0]?.plain_text ??\n  \"(untitled)\";\nconsole.log(`✓ Page accessible: \"${title}\" (${page.id})`);\n\n// 3. Append a test block to prove write access\nconst response = await notion.blocks.children.append({\n  block_id: pageId,\n  children: [\n    {\n      object: \"block\",\n      type: \"paragraph\",\n      paragraph: {\n        rich_text: [\n          {\n            type: \"text\",\n            text: { content: `API connection verified at ${new Date().toISOString()}` },\n          },\n        ],\n      },\n    },\n  ],\n});\nconsole.log(`✓ Write access confirmed (appended block ${response.results[0].id})`);\n\nconsole.log(\"\\nNotion API setup is working. Ready to go.\");\n"
}

File created successfully at: /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/scripts/verify-connection.mjs

{
  "file_path": "/Users/mattsteen/.claude/projects/-Users-mattsteen-dev-audits-notion-universal-baseline-2026-03-13-opus/memory/feedback_notion_integration_setup.md",
  "content": "---\nname: Notion integration setup path\ndescription: The correct URL path for creating Notion internal integrations vs public ones\ntype: feedback\n---\n\nWhen directing users to create a Notion internal integration, link to https://www.notion.so/profile/integrations and tell them to click \"Internal integrations\" in the left sidebar, then \"New integration\". The default landing page at that URL shows the public integration form which requires OAuth setup, company details, etc.\n\n**Why:** User landed on the public integration form and had to find the internal integrations section themselves.\n**How to apply:** Always specify \"Internal integrations\" sidebar link when giving Notion setup instructions.\n"
}

File created successfully at: /Users/mattsteen/.claude/projects/-Users-mattsteen-dev-audits-notion-universal-baseline-2026-03-13-opus/memory/feedback_notion_integration_setup.md

{
  "file_path": "/Users/mattsteen/.claude/projects/-Users-mattsteen-dev-audits-notion-universal-baseline-2026-03-13-opus/memory/MEMORY.md"
}

File does not exist. Note: your current working directory is /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus.

{
  "file_path": "/Users/mattsteen/.claude/projects/-Users-mattsteen-dev-audits-notion-universal-baseline-2026-03-13-opus/memory/MEMORY.md",
  "content": "# Memory Index\n\n- [feedback_notion_integration_setup.md](feedback_notion_integration_setup.md) — Correct URL/path for creating Notion internal integrations\n"
}

File created successfully at: /Users/mattsteen/.claude/projects/-Users-mattsteen-dev-audits-notion-universal-baseline-2026-03-13-opus/memory/MEMORY.md

{
  "file_path": "/Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.env",
  "content": "NOTION_TOKEN=ntn_[REDACTED]\nNOTION_TEST_PAGE_ID=32226b2ff6f1801c90d1fe890660d065\n"
}

File created successfully at: /Users/mattsteen/dev/audits/notion-universal-baseline-2026-03-13-opus/.env

{
  "command": "export $(cat .env | xargs) && node scripts/verify-connection.mjs 2>&1",
  "description": "Run Notion API verification script"
}

Exit code 1
node:internal/modules/run_main:107
    triggerUncaughtException(
    ^

[TypeError: fetch failed] {
  [cause]: Error: getaddrinfo ENOTFOUND api.notion.com
      at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:121:26) {
    errno: -3008,
    code: 'ENOTFOUND',
    syscall: 'getaddrinfo',
    hostname: 'api.notion.com'
  }
}

Node.js v25.6.1

{
  "command": "export $(cat .env | xargs) && node scripts/verify-connection.mjs 2>&1",
  "description": "Run Notion API verification script",
  "dangerouslyDisableSandbox": true
}

✓ Authenticated as: api-test (bot)
✓ Page accessible: "API Testing" (32226b2f-f6f1-801c-90d1-fe890660d065)
✓ Write access confirmed (appended block 32226b2f-f6f1-81e5-a895-d02eb71fc056)

Notion API setup is working. Ready to go.