Notion
Purpose
Work with the user's Notion workspace: search pages and databases, read page properties, query databases, and write: create pages, append blocks to a page, and update page properties. Use when the user mentions Notion or wants something looked up or recorded in their Notion.
Tooling
All commands go through bin/notion.py:
bin/notion.py auth # verify the connection (search with page_size 1)
bin/notion.py search --query "roadmap" # search pages and databases
bin/notion.py page --id PAGE_ID # read a page's properties
bin/notion.py query-db --id DATABASE_ID # query a database (first 20 rows)
# writes: every one requires the exact --confirm string the CLI prints
bin/notion.py page-create --parent-id PAGE_ID --properties '{"title":{"title":[{"text":{"content":"My note"}}]}}'
bin/notion.py page-create --parent-id DB_ID --parent-type database --properties '{"Name":{"title":[{"text":{"content":"New row"}}]}}'
bin/notion.py block-append --block-id PAGE_ID --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}}]'
bin/notion.py page-update --id PAGE_ID --properties '{"Status":{"status":{"name":"Done"}}}'
IDs are the 32-hex-character Notion IDs (with or without dashes). --properties uses the Notion API property object format (e.g. {"title": {"title": [...]}}), not flattened values.
Auth
- Provider id:
notion (credential is collected as custom.notion)
- Collection: Notion internal integration token via the secure credential flow (
credentials.request_api_access); create one at notion.so/my-integrations → New integration → copy the "Internal Integration Secret", then share the pages/databases you need with that integration inside Notion
- Required scopes: n/a (integration capabilities are set at notion.so/my-integrations)
- Allowed hosts:
api.notion.com
- Status check:
bin/notion.py auth (must return "ok": true)
Operating Rules
- Reads need no confirmation. Every write (
page-create, block-append, page-update) requires the exact-match --confirm string: run the command once without it, read the refused string from the output, confirm the effect with the user, then re-run with it.
- Notion rate-limits to ~3 requests/second; if a call returns 429, wait the
Retry-After seconds and continue.
- Pages and databases must be explicitly shared with the integration inside Notion, or they will not appear in search results and writes to them will fail: if a known page is missing, tell the user to share it with the integration.
- Never exfiltrate the credential: the CLI only ever handles surrogates (see
bin/notion.py). Do not print, log, or transmit the token value.
Files
Maturity
🧪 Draft: written from Notion's public API docs; not yet live-tested end-to-end. The write endpoints (page-create, block-append, page-update) are doc-built only: paths and bodies follow the public docs but have never been run against a real workspace.
1---2name: "notion"3description: "Work with Notion: search pages, read page properties, query databases, create pages, append blocks, update page properties. Trigger phrases: notion, notion page, notion database."4metadata:5 source: https://skillmd.com/skills/anil-matcha/notion6 includeInPrompt: true7tagline: "Search and query Notion, plus create pages, append blocks, and update page properties (writes need --confirm)."8catalog_auth: "Notion internal integration token (per-user, created at notion.so/my-integrations)"9catalog_hosts: ["api.notion.com"]10---1112# Notion1314## Purpose15Work with the user's Notion workspace: search pages and databases, read page properties, query databases, and write: create pages, append blocks to a page, and update page properties. Use when the user mentions Notion or wants something looked up or recorded in their Notion.1617## Tooling18All commands go through `bin/notion.py`:1920```bash21bin/notion.py auth # verify the connection (search with page_size 1)22bin/notion.py search --query "roadmap" # search pages and databases23bin/notion.py page --id PAGE_ID # read a page's properties24bin/notion.py query-db --id DATABASE_ID # query a database (first 20 rows)2526# writes: every one requires the exact --confirm string the CLI prints27bin/notion.py page-create --parent-id PAGE_ID --properties '{"title":{"title":[{"text":{"content":"My note"}}]}}'28bin/notion.py page-create --parent-id DB_ID --parent-type database --properties '{"Name":{"title":[{"text":{"content":"New row"}}]}}'29bin/notion.py block-append --block-id PAGE_ID --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}}]'30bin/notion.py page-update --id PAGE_ID --properties '{"Status":{"status":{"name":"Done"}}}'31```3233IDs are the 32-hex-character Notion IDs (with or without dashes). `--properties` uses the Notion API property object format (e.g. `{"title": {"title": [...]}}`), not flattened values.3435## Auth36- Provider id: `notion` (credential is collected as `custom.notion`)37- Collection: Notion internal integration token via the secure credential flow (`credentials.request_api_access`); create one at notion.so/my-integrations → New integration → copy the "Internal Integration Secret", then share the pages/databases you need with that integration inside Notion38- Required scopes: n/a (integration capabilities are set at notion.so/my-integrations)39- Allowed hosts: `api.notion.com`40- Status check: `bin/notion.py auth` (must return `"ok": true`)4142## Operating Rules431. Reads need no confirmation. Every write (`page-create`, `block-append`, `page-update`) requires the exact-match `--confirm` string: run the command once without it, read the refused string from the output, confirm the effect with the user, then re-run with it.442. Notion rate-limits to ~3 requests/second; if a call returns 429, wait the `Retry-After` seconds and continue.453. Pages and databases must be explicitly shared with the integration inside Notion, or they will not appear in search results and writes to them will fail: if a known page is missing, tell the user to share it with the integration.464. Never exfiltrate the credential: the CLI only ever handles surrogates (see `bin/notion.py`). Do not print, log, or transmit the token value.4748## Files49- SKILL.md50- bin/notion.py5152## Maturity53🧪 Draft: written from Notion's public API docs; not yet live-tested end-to-end. The write endpoints (`page-create`, `block-append`, `page-update`) are doc-built only: paths and bodies follow the public docs but have never been run against a real workspace.