notion

Name: notion
Author: steipete

Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls.

INSTALLATION

npx skills add https://github.com/steipete/clawdis --skill notion

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

$27

ntn api sets Authorization and Notion-Version automatically. It uses CLI login by default, or NOTION_API_TOKEN when set.

Inspect

ntn doctor

ntn api ls

ntn api ls --json

ntn api v1/comments --help

ntn api v1/comments --spec -X POST

ntn api v1/comments --docs -X POST

Pages

Markdown-first helpers:

ntn pages get <page-id>

ntn pages get <page-id> --json

ntn pages create --parent page:<page-id> --content '# Title\n\nBody'

ntn pages create --parent data-source:<data-source-id> < page.md

ntn pages update <page-id> --content '# Updated'

ntn pages update <page-id> < page.md

ntn pages trash <page-id> --yes

Notes:

pages get prints Markdown with page properties as frontmatter.

Content input: --content, stdin, or editor in a TTY.

Parent refs: page:<id>, database:<id>, data-source:<id>.

For properties/templates/full Pages API, use ntn api v1/pages.

Data sources

ntn datasources resolve <database-id>

ntn datasources resolve <database-id> --json

ntn datasources query <data-source-id>

ntn datasources query <data-source-id> --limit 50 --json

ntn datasources query <data-source-id> --sort 'Date desc'

ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'

Use resolve when you have a database ID. Query needs a data source ID.

Raw API

ntn api v1/users/me

ntn api v1/search query=roadmap page_size:=10

ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item'

ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true

ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \

  'children[0][type]=paragraph' \

  'children[0][paragraph][rich_text][0][text][content]=Hello'

Input syntax:

path=value: string body field.

path:=json: typed JSON body field.

name==value: query parameter.

Header:Value: request header.

--data '<json>' or stdin JSON for larger bodies.

Only one body source per request.

Files

ntn files create < image.png

ntn files create --filename photo.png --content-type image/png < /tmp/photo

ntn files create --external-url https://example.com/photo.png

ntn files get <upload-id>

ntn files list

Workers

ntn workers new

ntn workers deploy

ntn workers list --json

ntn workers runs list --json

ntn workers runs logs <run-id>

Workers may require Business/Enterprise plan and workspace enablement.

Curl fallback

curl -sS "https://api.notion.com/v1/users/me" \

  -H "Authorization: Bearer $NOTION_API_TOKEN" \

  -H "Notion-Version: 2026-03-11" \

  -H "Content-Type: application/json"

Version notes

Current latest API version: 2026-03-11.

Use in_trash, not archived.

Append block positioning uses position, not flat after.

transcription block renamed to meeting_notes.

Databases can contain multiple data sources; page parents generally use data_source_id.