Skill

Pass

Audit score 90

notion

Q: What's the difference between `ntn pages` and `ntn api v1/pages`?

`ntn pages` provides Markdown-first helpers for common operations (get, create, update, trash). `ntn api v1/pages` gives raw API access for advanced features like properties, templates, and full Pages API control.

Q: How do I authenticate without interactive login?

Set the `NOTION_API_TOKEN` environment variable with your API token, and optionally `NOTION_API_VERSION`. The CLI will use these instead of prompting for login.

Q: Can I query a database with filters and sorting?

Yes, use `ntn datasources query --filter ' ' --sort ' '`. You need the data source ID; use `ntn datasources resolve ` to convert a database ID.

steipete/clawdis

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

Source View on skills.sh

What is notion?

Official Notion CLI (`ntn`) and curl-based API access for managing pages, databases, files, and workspace data. Use this when you need to read/write Notion content, query data sources, upload files, or make raw API calls from code or scripts.

Create, read, update, and trash Notion pages with Markdown-first helpers
Query data sources and databases with filtering, sorting, and limit options
Upload and manage files (images, documents) with external URL support
Execute raw Notion API calls with typed JSON parameters and headers
Inspect API endpoints, specs, and documentation via `ntn doctor` and `ntn api`
Deploy and manage Notion Workers for automation (Business/Enterprise plans)

How to install notion

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

Prerequisites

Node.js and npm (for `ntn` CLI installation)
Notion workspace with API access enabled
Notion API token (via `ntn login` or `NOTION_API_TOKEN` environment variable)
Page IDs, database IDs, or data source IDs for the resources you want to access

Claude Code

Cursor

Windsurf

Cline

How to use notion

1.Install the official Notion CLI: `npm install -g ntn`
2.Authenticate: run `ntn login` or set `NOTION_API_TOKEN` environment variable
3.Inspect available endpoints: `ntn doctor` and `ntn api ls`
4.Use Markdown helpers for pages: `ntn pages get <id>`, `ntn pages create`, `ntn pages update`
5.Query data sources: `ntn datasources query <id> --filter '...' --sort '...'`
6.For advanced operations, use raw API: `ntn api v1/<endpoint> <args>`
7.Upload files: `ntn files create < file.png`
8.Deploy Workers (if enabled): `ntn workers new` and `ntn workers deploy`

Use cases

Good for

Sync Notion pages to external systems or generate reports from database queries
Bulk create or update pages programmatically from Markdown templates
Upload files to Notion and embed them in pages
Query filtered/sorted data sources to extract specific records
Automate workspace tasks via Workers or scheduled scripts

Who it's for

Backend developers integrating Notion with applications
DevOps engineers automating documentation and knowledge base updates
Data analysts querying Notion databases for reporting
Automation engineers building Notion-based workflows
Teams using Notion as a data source for CI/CD or ETL pipelines

notion FAQ

What's the difference between `ntn pages` and `ntn api v1/pages`?

`ntn pages` provides Markdown-first helpers for common operations (get, create, update, trash). `ntn api v1/pages` gives raw API access for advanced features like properties, templates, and full Pages API control.

How do I authenticate without interactive login?

Set the `NOTION_API_TOKEN` environment variable with your API token, and optionally `NOTION_API_VERSION`. The CLI will use these instead of prompting for login.

Can I query a database with filters and sorting?

Yes, use `ntn datasources query <id> --filter '<json>' --sort '<field> <direction>'`. You need the data source ID; use `ntn datasources resolve <database-id>` to convert a database ID.

What input formats does `ntn api` support?

`path=value` for strings, `path:=json` for typed JSON, `name==value` for query params, `Header:Value` for headers, and `--data '<json>'` or stdin for larger bodies.

Are Notion Workers available for all plans?

No, Workers may require a Business or Enterprise plan and must be enabled by your workspace administrator.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: notion description: "Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls." homepage: https://developers.notion.com/cli/get-started/overview metadata: { "openclaw": { "emoji": "📝", "requires": { "anyBins": ["ntn", "curl"] }, "primaryEnv": "NOTION_API_TOKEN", "install": [ { "id": "node", "kind": "node", "package": "ntn", "bins": ["ntn"], "label": "Install official Notion CLI (npm)", }, ], }, }

Notion

Prefer official ntn CLI. Use curl only when ntn is unavailable or a raw request is clearer.

Setup

npm install -g ntn
ntn --version
ntn login

Script/headless auth:

export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11

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.