[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A34RN4RTQFSF7RJBA42G9V":3,"skill-same:01M7A34RN4RTQFSF7RJBA42G9V":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":14,"repositoryHtmlUrl":47,"repositoryHomepageUrl":6,"ownerHtmlUrl":48,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":49,"install":50,"resources":63},"01M7A34RN4RTQFSF7RJBA42G9V","notion",null,"Notion API + ntn CLI: pages, databases, markdown, Workers.","12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI","12103541","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F48291538?v=4","01M7A2PSM93DH9YY7EHRK5RF27","NAWAWI","01M7A2PSMSGV0S7KCD9312BN4M",0,"MIT","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fnotion\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: notion\ndescription: \"Notion API + ntn CLI: pages, databases, markdown, Workers.\"\nversion: 2.0.0\nauthor: community\nlicense: MIT\nplatforms: [linux, macos, windows]\nprerequisites:\n  env_vars: [NOTION_API_KEY]\nmetadata:\n  hermes:\n    tags: [Notion, Productivity, Notes, Database, API, CLI, Workers]\n    homepage: https:\u002F\u002Fdevelopers.notion.com\n---\n\n# Notion\n\nTalk to Notion two ways. Same integration token works for both — pick by what's available.\n\n◆ **`ntn` CLI** — Notion's official CLI. Shorter syntax, one-line file uploads, required for Workers. macOS + Linux only as of May 2026 (Windows support \"coming soon\"). **Default when installed.**\n◆ **HTTP + curl** — works everywhere including Windows. **Default fallback** when `ntn` isn't installed.\n\n## Setup\n\n### 1. Get an integration token (required for both paths)\n\n1. Create an integration at https:\u002F\u002Fnotion.so\u002Fmy-integrations\n2. Copy the API key (starts with `ntn_` or `secret_`)\n3. Store in `${HERMES_HOME:-~\u002F.hermes}\u002F.env`:\n   ```\n   NOTION_API_KEY=ntn_your_key_here\n   ```\n4. **Share target pages\u002Fdatabases with the integration** in Notion: page menu `...` → `Connect to` → your integration name. Without this, the API returns 404 for that page even though it exists.\n\n### 2. Install `ntn` (preferred path on macOS \u002F Linux)\n\n```bash\n# Recommended\ncurl -fsSL https:\u002F\u002Fntn.dev | bash\n\n# Or via npm (needs Node 22+, npm 10+)\nnpm install --global ntn\n\nntn --version    # verify\n```\n\n**Skip `ntn login` — use the integration token instead.** This works headlessly, no browser needed:\n```bash\nexport NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN\nexport NOTION_KEYRING=0                       # don't try to use the OS keychain\n```\n\nAdd those exports to your shell profile (or to `${HERMES_HOME:-~\u002F.hermes}\u002F.env`) so every session inherits them.\n\n### 3. Choose path at runtime\n\n```bash\nif command -v ntn >\u002Fdev\u002Fnull 2>&1; then\n  # use ntn\nelse\n  # fall back to curl\nfi\n```\n\nWindows users: skip step 2 entirely until native `ntn` ships — Path B works fine. If you want CLI ergonomics now, install `ntn` inside WSL2.\n\n## API Basics\n\n`Notion-Version: 2025-09-03` is required on all HTTP requests. `ntn` handles this for you. In this version, what users call \"databases\" are called **data sources** in the API.\n\n## Path A — `ntn` CLI (preferred, macOS \u002F Linux)\n\n### Raw API calls (shorthand for curl)\n```bash\nntn api v1\u002Fusers                                  # GET\nntn api v1\u002Fpages parent[page_id]=abc123 \\         # POST with inline body\n  properties[title][0][text][content]=\"Notes\"\nntn api v1\u002Fpages\u002Fabc123 -X PATCH archived:=true   # PATCH; := is non-string (bool\u002Fnum\u002Fnull)\n```\n\nSyntax notes:\n- `key=value` — string fields\n- `key[nested]=value` — nested object fields\n- `key:=value` — typed assignment (booleans, numbers, null, arrays)\n\n### Search\n```bash\nntn api v1\u002Fsearch query=\"page title\"\n```\n\n### Read page metadata\n```bash\nntn api v1\u002Fpages\u002F{page_id}\n```\n\n### Read page as Markdown (agent-friendly)\n```bash\nntn api v1\u002Fpages\u002F{page_id}\u002Fmarkdown\n```\n\n### Read page content as blocks\n```bash\nntn api v1\u002Fblocks\u002F{page_id}\u002Fchildren\n```\n\n### Create page from Markdown\n```bash\nntn api v1\u002Fpages \\\n  parent[page_id]=xxx \\\n  properties[title][0][text][content]=\"Notes from meeting\" \\\n  markdown=\"# Agenda\n\n- Q3 roadmap\n- Hiring\"\n```\n\n### Patch a page with Markdown\n```bash\nntn api v1\u002Fpages\u002F{page_id}\u002Fmarkdown -X PATCH \\\n  markdown=\"## Update\n\nShipped the prototype.\"\n```\n\n### Query a database (data source)\n```bash\nntn api v1\u002Fdata_sources\u002F{data_source_id}\u002Fquery -X POST \\\n  filter[property]=Status filter[select][equals]=Active\n```\n\nFor complex queries with `sorts`, multiple filter clauses, or compound logic, pipe JSON in:\n```bash\necho '{\"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}}, \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]}' | \\\n  ntn api v1\u002Fdata_sources\u002F{data_source_id}\u002Fquery -X POST --json -\n```\n\n### File uploads (one-liner — biggest CLI win)\n```bash\nntn files create \u003C photo.png\nntn files create --external-url https:\u002F\u002Fexample.com\u002Fphoto.png\nntn files list\n```\n\nCompare to the 3-step HTTP flow (create upload → PUT bytes → reference).\n\n### Useful env vars\n| Var | Effect |\n|---|---|\n| `NOTION_API_TOKEN` | Auth token (overrides keychain) — set this to your integration token |\n| `NOTION_KEYRING=0` | File-based creds at `~\u002F.config\u002Fnotion\u002Fauth.json` instead of OS keychain |\n| `NOTION_WORKSPACE_ID` | Skip the workspace picker prompt |\n\n## Path B — HTTP + curl (cross-platform, default on Windows)\n\nAll requests share this pattern:\n\n```bash\ncurl -s -X GET \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002F...\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\"\n```\n\nOn Windows the `curl` shipped with Windows 10+ works as-is. PowerShell users can also use `Invoke-RestMethod`.\n\n### Search\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fsearch\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\": \"page title\"}'\n```\n\n### Read page metadata\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Read page as Markdown (agent-friendly)\n\nEasier to feed to a model than block JSON.\n\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\u002Fmarkdown\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Read page content as blocks (when you need structure)\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fblocks\u002F{page_id}\u002Fchildren\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Create page from Markdown\n\n`POST \u002Fv1\u002Fpages` accepts a `markdown` body param.\n\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"properties\": {\"title\": [{\"text\": {\"content\": \"Notes from meeting\"}}]},\n    \"markdown\": \"# Agenda\\n\\n- Q3 roadmap\\n- Hiring\\n\\n## Decisions\\n- Ship MVP Friday\"\n  }'\n```\n\n### Patch a page with Markdown\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\u002Fmarkdown\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"markdown\": \"## Update\\n\\nShipped the prototype.\"}'\n```\n\n### Create page in a database (typed properties)\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"database_id\": \"xxx\"},\n    \"properties\": {\n      \"Name\": {\"title\": [{\"text\": {\"content\": \"New Item\"}}]},\n      \"Status\": {\"select\": {\"name\": \"Todo\"}}\n    }\n  }'\n```\n\n### Query a database (data source)\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fdata_sources\u002F{data_source_id}\u002Fquery\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}},\n    \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]\n  }'\n```\n\n### Create a database\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fdata_sources\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"title\": [{\"text\": {\"content\": \"My Database\"}}],\n    \"properties\": {\n      \"Name\": {\"title\": {}},\n      \"Status\": {\"select\": {\"options\": [{\"name\": \"Todo\"}, {\"name\": \"Done\"}]}},\n      \"Date\": {\"date\": {}}\n    }\n  }'\n```\n\n### Update page properties\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"properties\": {\"Status\": {\"select\": {\"name\": \"Done\"}}}}'\n```\n\n### Append blocks to a page\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fblocks\u002F{page_id}\u002Fchildren\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"children\": [\n      {\"object\": \"block\", \"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"text\": {\"content\": \"Hello from Hermes!\"}}]}}\n    ]\n  }'\n```\n\n### File uploads (3-step flow)\n```bash\n# 1. Create upload\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Ffile_uploads\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filename\": \"photo.png\", \"content_type\": \"image\u002Fpng\"}'\n\n# 2. PUT bytes to the upload_url returned above\ncurl -s -X PUT \"{upload_url}\" --data-binary @photo.png\n\n# 3. Reference {file_upload_id} in a page\u002Fblock payload\n```\n\n## Property Types\n\nCommon property formats for database items:\n\n- **Title:** `{\"title\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Rich text:** `{\"rich_text\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Select:** `{\"select\": {\"name\": \"Option\"}}`\n- **Multi-select:** `{\"multi_select\": [{\"name\": \"A\"}, {\"name\": \"B\"}]}`\n- **Date:** `{\"date\": {\"start\": \"2026-01-15\", \"end\": \"2026-01-16\"}}`\n- **Checkbox:** `{\"checkbox\": true}`\n- **Number:** `{\"number\": 42}`\n- **URL:** `{\"url\": \"https:\u002F\u002F...\"}`\n- **Email:** `{\"email\": \"user@example.com\"}`\n- **Relation:** `{\"relation\": [{\"id\": \"page_id\"}]}`\n\n## API Version 2025-09-03 — Databases vs Data Sources\n\n- **Databases became data sources.** Use `\u002Fdata_sources\u002F` endpoints for queries and retrieval.\n- **Two IDs per database:** `database_id` and `data_source_id`.\n  - `database_id` when creating pages: `parent: {\"database_id\": \"...\"}`\n  - `data_source_id` when querying: `POST \u002Fv1\u002Fdata_sources\u002F{id}\u002Fquery`\n- Search returns databases as `\"object\": \"data_source\"` with the `data_source_id` field.\n\n## Notion Workers (advanced, requires `ntn`)\n\nWorkers are TypeScript programs Notion hosts for you. One worker can expose any combination of:\n- **Syncs** — pull data from external APIs into a Notion database on a schedule (default 30 min).\n- **Tools** — appear as callable tools inside Notion's Custom Agents.\n- **Webhooks** — receive HTTP events from external services (GitHub, Stripe, etc.) and act in Notion.\n\n**Plan \u002F platform gating:**\n- CLI works on all plans. **Deploying Workers requires Business or Enterprise.**\n- `ntn` is macOS\u002FLinux only as of May 2026. Windows users need WSL2 or to wait for native support.\n- Free through August 11, 2026; metered on Notion credits after.\n\n### Minimal Worker\n\n```bash\nntn workers new my-worker      # scaffold\ncd my-worker\n# Edit src\u002Findex.ts\nntn workers deploy --name my-worker\n```\n\n`src\u002Findex.ts`:\n```typescript\nimport { Worker } from \"@notionhq\u002Fworkers\";\n\nconst worker = new Worker();\nexport default worker;\n\nworker.tool(\"greet\", {\n  title: \"Greet a User\",\n  description: \"Returns a friendly greeting\",\n  inputSchema: { type: \"object\", properties: { name: { type: \"string\" } }, required: [\"name\"] },\n  execute: async ({ name }) => `Hello, ${name}!`,\n});\n```\n\n### Webhook capability\n\n```typescript\nworker.webhook(\"onGithubPush\", {\n  title: \"GitHub Push Handler\",\n  execute: async (events, { notion }) => {\n    for (const event of events) {\n      \u002F\u002F event.body, event.rawBody (for signature verification), event.headers\n      console.log(\"got delivery\", event.deliveryId);\n    }\n  },\n});\n```\n\nAfter deploy: `ntn workers webhooks list` shows the URL Notion generates. Treat that URL as a secret — anyone with it can POST events unless you add signature verification.\n\n### Worker lifecycle commands\n\n```bash\nntn workers deploy\nntn workers list\nntn workers exec \u003Ccapability-key> -d '{\"name\": \"world\"}'\nntn workers sync trigger \u003Ckey>            # run a sync now\nntn workers sync pause \u003Ckey>\nntn workers env set GITHUB_WEBHOOK_SECRET=...\nntn workers runs list                     # recent invocations\nntn workers runs logs \u003Crun-id>\nntn workers webhooks list\n```\n\nWhen asked to build a Worker, scaffold with `ntn workers new`, write the code in `src\u002Findex.ts`, set any secrets with `ntn workers env set`, and deploy. Notion's docs at https:\u002F\u002Fdevelopers.notion.com\u002Fworkers cover the full API surface.\n\n## Notion-Flavored Markdown (used by `\u002Fmarkdown` endpoints)\n\nStandard CommonMark plus XML-like tags for Notion-specific blocks. Use **tabs** for indentation.\n\n**Blocks beyond CommonMark:**\n```\n\u003Ccallout icon=\"🎯\" color=\"blue_bg\">\n\tShip the MVP by **Friday**.\n\u003C\u002Fcallout>\n\n\u003Cdetails color=\"gray\">\n\u003Csummary>Toggle title\u003C\u002Fsummary>\n\tChildren indented one tab\n\u003C\u002Fdetails>\n\n\u003Ccolumns>\n\t\u003Ccolumn>Left side\u003C\u002Fcolumn>\n\t\u003Ccolumn>Right side\u003C\u002Fcolumn>\n\u003C\u002Fcolumns>\n\n\u003Ctable_of_contents color=\"gray\"\u002F>\n```\n\n**Inline:**\n- Mentions: `\u003Cmention-user url=\"...\"\u002F>`, `\u003Cmention-page url=\"...\">Title\u003C\u002Fmention-page>`, `\u003Cmention-date start=\"2026-05-15\"\u002F>`\n- Underline: `\u003Cspan underline=\"true\">text\u003C\u002Fspan>`\n- Color: `\u003Cspan color=\"blue\">text\u003C\u002Fspan>` or block-level `{color=\"blue\"}` on the first line\n- Math: inline `$x^2$`, block `$$ ... $$`\n- Citations: `[^https:\u002F\u002Fexample.com]`\n\n**Colors:** `gray brown orange yellow green blue purple pink red`, plus `*_bg` variants for backgrounds.\n\nHeadings 5\u002F6 collapse to H4. Multiple `>` lines render as separate quote blocks — use `\u003Cbr>` inside a single `>` for multi-line quotes.\n\n## Choosing the Right Path\n\n| Task | mac \u002F Linux | Windows |\n|---|---|---|\n| Read\u002Fwrite pages, search, query databases | `ntn api ...` | curl |\n| Read a page for an agent to summarize | `ntn api v1\u002Fpages\u002F{id}\u002Fmarkdown` | curl `\u002Fmarkdown` endpoint |\n| Upload a file | `ntn files create \u003C file` | 3-step HTTP flow |\n| One-off API exploration | `ntn api ...` | curl |\n| Build a sync \u002F webhook \u002F agent tool hosted by Notion | `ntn workers ...` | WSL2 + `ntn workers ...` |\n\n## Notes\n\n- Page\u002Fdatabase IDs are UUIDs (with or without dashes — both accepted).\n- Rate limit: ~3 requests\u002Fsecond average. The CLI doesn't bypass this.\n- The API cannot set database **view** filters — that's UI-only.\n- Use `\"is_inline\": true` when creating data sources to embed them in a page.\n- Always pass `-s` to curl to suppress progress bars (cleaner agent output).\n- Pipe JSON through `jq` when reading: `... | jq '.results[0].properties'`.\n- Notion also ships an MCP server now (`Notion MCP`, ~91% more token-efficient on DB ops than the previous version) — wire it via Hermes' MCP support if you want streaming Notion access from inside a session, but the paths above are enough for most one-shot tasks.\n","# Notion\n\nTalk to Notion two ways. Same integration token works for both — pick by what's available.\n\n◆ **`ntn` CLI** — Notion's official CLI. Shorter syntax, one-line file uploads, required for Workers. macOS + Linux only as of May 2026 (Windows support \"coming soon\"). **Default when installed.**\n◆ **HTTP + curl** — works everywhere including Windows. **Default fallback** when `ntn` isn't installed.\n\n## Setup\n\n### 1. Get an integration token (required for both paths)\n\n1. Create an integration at https:\u002F\u002Fnotion.so\u002Fmy-integrations\n2. Copy the API key (starts with `ntn_` or `secret_`)\n3. Store in `${HERMES_HOME:-~\u002F.hermes}\u002F.env`:\n   ```\n   NOTION_API_KEY=ntn_your_key_here\n   ```\n4. **Share target pages\u002Fdatabases with the integration** in Notion: page menu `...` → `Connect to` → your integration name. Without this, the API returns 404 for that page even though it exists.\n\n### 2. Install `ntn` (preferred path on macOS \u002F Linux)\n\n```bash\n# Recommended\ncurl -fsSL https:\u002F\u002Fntn.dev | bash\n\n# Or via npm (needs Node 22+, npm 10+)\nnpm install --global ntn\n\nntn --version    # verify\n```\n\n**Skip `ntn login` — use the integration token instead.** This works headlessly, no browser needed:\n```bash\nexport NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN\nexport NOTION_KEYRING=0                       # don't try to use the OS keychain\n```\n\nAdd those exports to your shell profile (or to `${HERMES_HOME:-~\u002F.hermes}\u002F.env`) so every session inherits them.\n\n### 3. Choose path at runtime\n\n```bash\nif command -v ntn >\u002Fdev\u002Fnull 2>&1; then\n  # use ntn\nelse\n  # fall back to curl\nfi\n```\n\nWindows users: skip step 2 entirely until native `ntn` ships — Path B works fine. If you want CLI ergonomics now, install `ntn` inside WSL2.\n\n## API Basics\n\n`Notion-Version: 2025-09-03` is required on all HTTP requests. `ntn` handles this for you. In this version, what users call \"databases\" are called **data sources** in the API.\n\n## Path A — `ntn` CLI (preferred, macOS \u002F Linux)\n\n### Raw API calls (shorthand for curl)\n```bash\nntn api v1\u002Fusers                                  # GET\nntn api v1\u002Fpages parent[page_id]=abc123 \\         # POST with inline body\n  properties[title][0][text][content]=\"Notes\"\nntn api v1\u002Fpages\u002Fabc123 -X PATCH archived:=true   # PATCH; := is non-string (bool\u002Fnum\u002Fnull)\n```\n\nSyntax notes:\n- `key=value` — string fields\n- `key[nested]=value` — nested object fields\n- `key:=value` — typed assignment (booleans, numbers, null, arrays)\n\n### Search\n```bash\nntn api v1\u002Fsearch query=\"page title\"\n```\n\n### Read page metadata\n```bash\nntn api v1\u002Fpages\u002F{page_id}\n```\n\n### Read page as Markdown (agent-friendly)\n```bash\nntn api v1\u002Fpages\u002F{page_id}\u002Fmarkdown\n```\n\n### Read page content as blocks\n```bash\nntn api v1\u002Fblocks\u002F{page_id}\u002Fchildren\n```\n\n### Create page from Markdown\n```bash\nntn api v1\u002Fpages \\\n  parent[page_id]=xxx \\\n  properties[title][0][text][content]=\"Notes from meeting\" \\\n  markdown=\"# Agenda\n\n- Q3 roadmap\n- Hiring\"\n```\n\n### Patch a page with Markdown\n```bash\nntn api v1\u002Fpages\u002F{page_id}\u002Fmarkdown -X PATCH \\\n  markdown=\"## Update\n\nShipped the prototype.\"\n```\n\n### Query a database (data source)\n```bash\nntn api v1\u002Fdata_sources\u002F{data_source_id}\u002Fquery -X POST \\\n  filter[property]=Status filter[select][equals]=Active\n```\n\nFor complex queries with `sorts`, multiple filter clauses, or compound logic, pipe JSON in:\n```bash\necho '{\"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}}, \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]}' | \\\n  ntn api v1\u002Fdata_sources\u002F{data_source_id}\u002Fquery -X POST --json -\n```\n\n### File uploads (one-liner — biggest CLI win)\n```bash\nntn files create \u003C photo.png\nntn files create --external-url https:\u002F\u002Fexample.com\u002Fphoto.png\nntn files list\n```\n\nCompare to the 3-step HTTP flow (create upload → PUT bytes → reference).\n\n### Useful env vars\n| Var | Effect |\n|---|---|\n| `NOTION_API_TOKEN` | Auth token (overrides keychain) — set this to your integration token |\n| `NOTION_KEYRING=0` | File-based creds at `~\u002F.config\u002Fnotion\u002Fauth.json` instead of OS keychain |\n| `NOTION_WORKSPACE_ID` | Skip the workspace picker prompt |\n\n## Path B — HTTP + curl (cross-platform, default on Windows)\n\nAll requests share this pattern:\n\n```bash\ncurl -s -X GET \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002F...\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\"\n```\n\nOn Windows the `curl` shipped with Windows 10+ works as-is. PowerShell users can also use `Invoke-RestMethod`.\n\n### Search\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fsearch\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\": \"page title\"}'\n```\n\n### Read page metadata\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Read page as Markdown (agent-friendly)\n\nEasier to feed to a model than block JSON.\n\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\u002Fmarkdown\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Read page content as blocks (when you need structure)\n```bash\ncurl -s \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fblocks\u002F{page_id}\u002Fchildren\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n### Create page from Markdown\n\n`POST \u002Fv1\u002Fpages` accepts a `markdown` body param.\n\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"properties\": {\"title\": [{\"text\": {\"content\": \"Notes from meeting\"}}]},\n    \"markdown\": \"# Agenda\\n\\n- Q3 roadmap\\n- Hiring\\n\\n## Decisions\\n- Ship MVP Friday\"\n  }'\n```\n\n### Patch a page with Markdown\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\u002Fmarkdown\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"markdown\": \"## Update\\n\\nShipped the prototype.\"}'\n```\n\n### Create page in a database (typed properties)\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"database_id\": \"xxx\"},\n    \"properties\": {\n      \"Name\": {\"title\": [{\"text\": {\"content\": \"New Item\"}}]},\n      \"Status\": {\"select\": {\"name\": \"Todo\"}}\n    }\n  }'\n```\n\n### Query a database (data source)\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fdata_sources\u002F{data_source_id}\u002Fquery\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}},\n    \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]\n  }'\n```\n\n### Create a database\n```bash\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fdata_sources\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"title\": [{\"text\": {\"content\": \"My Database\"}}],\n    \"properties\": {\n      \"Name\": {\"title\": {}},\n      \"Status\": {\"select\": {\"options\": [{\"name\": \"Todo\"}, {\"name\": \"Done\"}]}},\n      \"Date\": {\"date\": {}}\n    }\n  }'\n```\n\n### Update page properties\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002F{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"properties\": {\"Status\": {\"select\": {\"name\": \"Done\"}}}}'\n```\n\n### Append blocks to a page\n```bash\ncurl -s -X PATCH \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fblocks\u002F{page_id}\u002Fchildren\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"children\": [\n      {\"object\": \"block\", \"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"text\": {\"content\": \"Hello from Hermes!\"}}]}}\n    ]\n  }'\n```\n\n### File uploads (3-step flow)\n```bash\n# 1. Create upload\ncurl -s -X POST \"https:\u002F\u002Fapi.notion.com\u002Fv1\u002Ffile_uploads\" \\\n  -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filename\": \"photo.png\", \"content_type\": \"image\u002Fpng\"}'\n\n# 2. PUT bytes to the upload_url returned above\ncurl -s -X PUT \"{upload_url}\" --data-binary @photo.png\n\n# 3. Reference {file_upload_id} in a page\u002Fblock payload\n```\n\n## Property Types\n\nCommon property formats for database items:\n\n- **Title:** `{\"title\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Rich text:** `{\"rich_text\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Select:** `{\"select\": {\"name\": \"Option\"}}`\n- **Multi-select:** `{\"multi_select\": [{\"name\": \"A\"}, {\"name\": \"B\"}]}`\n- **Date:** `{\"date\": {\"start\": \"2026-01-15\", \"end\": \"2026-01-16\"}}`\n- **Checkbox:** `{\"checkbox\": true}`\n- **Number:** `{\"number\": 42}`\n- **URL:** `{\"url\": \"https:\u002F\u002F...\"}`\n- **Email:** `{\"email\": \"user@example.com\"}`\n- **Relation:** `{\"relation\": [{\"id\": \"page_id\"}]}`\n\n## API Version 2025-09-03 — Databases vs Data Sources\n\n- **Databases became data sources.** Use `\u002Fdata_sources\u002F` endpoints for queries and retrieval.\n- **Two IDs per database:** `database_id` and `data_source_id`.\n  - `database_id` when creating pages: `parent: {\"database_id\": \"...\"}`\n  - `data_source_id` when querying: `POST \u002Fv1\u002Fdata_sources\u002F{id}\u002Fquery`\n- Search returns databases as `\"object\": \"data_source\"` with the `data_source_id` field.\n\n## Notion Workers (advanced, requires `ntn`)\n\nWorkers are TypeScript programs Notion hosts for you. One worker can expose any combination of:\n- **Syncs** — pull data from external APIs into a Notion database on a schedule (default 30 min).\n- **Tools** — appear as callable tools inside Notion's Custom Agents.\n- **Webhooks** — receive HTTP events from external services (GitHub, Stripe, etc.) and act in Notion.\n\n**Plan \u002F platform gating:**\n- CLI works on all plans. **Deploying Workers requires Business or Enterprise.**\n- `ntn` is macOS\u002FLinux only as of May 2026. Windows users need WSL2 or to wait for native support.\n- Free through August 11, 2026; metered on Notion credits after.\n\n### Minimal Worker\n\n```bash\nntn workers new my-worker      # scaffold\ncd my-worker\n# Edit src\u002Findex.ts\nntn workers deploy --name my-worker\n```\n\n`src\u002Findex.ts`:\n```typescript\nimport { Worker } from \"@notionhq\u002Fworkers\";\n\nconst worker = new Worker();\nexport default worker;\n\nworker.tool(\"greet\", {\n  title: \"Greet a User\",\n  description: \"Returns a friendly greeting\",\n  inputSchema: { type: \"object\", properties: { name: { type: \"string\" } }, required: [\"name\"] },\n  execute: async ({ name }) => `Hello, ${name}!`,\n});\n```\n\n### Webhook capability\n\n```typescript\nworker.webhook(\"onGithubPush\", {\n  title: \"GitHub Push Handler\",\n  execute: async (events, { notion }) => {\n    for (const event of events) {\n      \u002F\u002F event.body, event.rawBody (for signature verification), event.headers\n      console.log(\"got delivery\", event.deliveryId);\n    }\n  },\n});\n```\n\nAfter deploy: `ntn workers webhooks list` shows the URL Notion generates. Treat that URL as a secret — anyone with it can POST events unless you add signature verification.\n\n### Worker lifecycle commands\n\n```bash\nntn workers deploy\nntn workers list\nntn workers exec \u003Ccapability-key> -d '{\"name\": \"world\"}'\nntn workers sync trigger \u003Ckey>            # run a sync now\nntn workers sync pause \u003Ckey>\nntn workers env set GITHUB_WEBHOOK_SECRET=...\nntn workers runs list                     # recent invocations\nntn workers runs logs \u003Crun-id>\nntn workers webhooks list\n```\n\nWhen asked to build a Worker, scaffold with `ntn workers new`, write the code in `src\u002Findex.ts`, set any secrets with `ntn workers env set`, and deploy. Notion's docs at https:\u002F\u002Fdevelopers.notion.com\u002Fworkers cover the full API surface.\n\n## Notion-Flavored Markdown (used by `\u002Fmarkdown` endpoints)\n\nStandard CommonMark plus XML-like tags for Notion-specific blocks. Use **tabs** for indentation.\n\n**Blocks beyond CommonMark:**\n```\n\u003Ccallout icon=\"🎯\" color=\"blue_bg\">\n\tShip the MVP by **Friday**.\n\u003C\u002Fcallout>\n\n\u003Cdetails color=\"gray\">\n\u003Csummary>Toggle title\u003C\u002Fsummary>\n\tChildren indented one tab\n\u003C\u002Fdetails>\n\n\u003Ccolumns>\n\t\u003Ccolumn>Left side\u003C\u002Fcolumn>\n\t\u003Ccolumn>Right side\u003C\u002Fcolumn>\n\u003C\u002Fcolumns>\n\n\u003Ctable_of_contents color=\"gray\"\u002F>\n```\n\n**Inline:**\n- Mentions: `\u003Cmention-user url=\"...\"\u002F>`, `\u003Cmention-page url=\"...\">Title\u003C\u002Fmention-page>`, `\u003Cmention-date start=\"2026-05-15\"\u002F>`\n- Underline: `\u003Cspan underline=\"true\">text\u003C\u002Fspan>`\n- Color: `\u003Cspan color=\"blue\">text\u003C\u002Fspan>` or block-level `{color=\"blue\"}` on the first line\n- Math: inline `$x^2$`, block `$$ ... $$`\n- Citations: `[^https:\u002F\u002Fexample.com]`\n\n**Colors:** `gray brown orange yellow green blue purple pink red`, plus `*_bg` variants for backgrounds.\n\nHeadings 5\u002F6 collapse to H4. Multiple `>` lines render as separate quote blocks — use `\u003Cbr>` inside a single `>` for multi-line quotes.\n\n## Choosing the Right Path\n\n| Task | mac \u002F Linux | Windows |\n|---|---|---|\n| Read\u002Fwrite pages, search, query databases | `ntn api ...` | curl |\n| Read a page for an agent to summarize | `ntn api v1\u002Fpages\u002F{id}\u002Fmarkdown` | curl `\u002Fmarkdown` endpoint |\n| Upload a file | `ntn files create \u003C file` | 3-step HTTP flow |\n| One-off API exploration | `ntn api ...` | curl |\n| Build a sync \u002F webhook \u002F agent tool hosted by Notion | `ntn workers ...` | WSL2 + `ntn workers ...` |\n\n## Notes\n\n- Page\u002Fdatabase IDs are UUIDs (with or without dashes — both accepted).\n- Rate limit: ~3 requests\u002Fsecond average. The CLI doesn't bypass this.\n- The API cannot set database **view** filters — that's UI-only.\n- Use `\"is_inline\": true` when creating data sources to embed them in a page.\n- Always pass `-s` to curl to suppress progress bars (cleaner agent output).\n- Pipe JSON through `jq` when reading: `... | jq '.results[0].properties'`.\n- Notion also ships an MCP server now (`Notion MCP`, ~91% more token-efficient on DB ops than the previous version) — wire it via Hermes' MCP support if you want streaming Notion access from inside a session, but the paths above are enough for most one-shot tasks.\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":37,"description":7,"prerequisites":41},"community","2.0.0",{"hermes":27},{"tags":28,"homepage":36},[29,30,31,32,33,34,35],"Notion","Productivity","Notes","Database","API","CLI","Workers","https:\u002F\u002Fdevelopers.notion.com",[38,39,40],"linux","macos","windows",{"env_vars":42},[43],"NOTION_API_KEY","main","96bab5c1e3ed763a77711f59b371e678af30971d","skills\u002Fproductivity\u002Fnotion","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI","https:\u002F\u002Fgithub.com\u002F12103541","2026-08-04 09:54:44",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add 12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI --skill notion",{"tool":56,"command":57},"bunx","bunx skills add 12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI --skill notion",{"tool":59,"command":60},"pnpm","pnpm dlx skills add 12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI --skill notion","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fnotion\u002FSKILL.md",true,[64],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fblock-types.md","REFERENCE","参考文档",3021,"https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fnotion\u002Freferences\u002Fblock-types.md",[71,78,85,92,99,106],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7A39S6PZQ8P0NYNNW6BDC8V","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7A39MWGGFPJ2VXT2EJD8JAD","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7A39J23RCZQ6JS773JX0CT6","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7A39FQNTYVFXDGTCGY9HSTT","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7A39CRM98DQ8K3B89MYBWVN","requesting-code-review","Pre-commit review: security scan, quality gates, auto-fix.","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Frequesting-code-review\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":19},"01M7A398Q7J4YEFPWVZBXMW769","python-debugpy","Debug Python: pdb REPL + debugpy remote (DAP).","https:\u002F\u002Fgithub.com\u002F12103541\u002FBACKUP-SKILLS-TOOLS-MCP-MEMORI\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fpython-debugpy\u002FSKILL.md",[],[]]