notion

Manage Notion pages, databases, and Workers via the Notion API and ntn CLI.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/CHENHUI-X/toolbox --skill notion-chenhui-x
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: notion
Source: https://github.com/CHENHUI-X/toolbox/tree/main/official-skills/productivity/notion
Command: npx skills add https://github.com/CHENHUI-X/toolbox --skill notion-chenhui-x

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Working with Notion programmatically requires juggling API versioning, authentication, block JSON structures, and platform-specific tooling. This Skill provides ready-to-use commands for reading, creating, and updating Notion pages and databases through either the official ntn CLI or plain curl, so you never have to look up endpoint syntax mid-task. ## Core Features & Use Cases - Dual-path API access: Use the ntn CLI on macOS/Linux for shorthand commands and one-line file uploads, or fall back to curl with the Notion API on any platform including Windows. - Markdown-native workflows: Read pages as Markdown for agent-friendly summarization, and create or patch pages directly from Markdown content instead of raw block JSON. - Database and data source operations: Query data sources with filters and sorts, create databases with typed properties, and update page properties like status, dates, and relations. - Notion Workers: Scaffold, deploy, and manage TypeScript Workers that run syncs, expose agent tools, and receive webhooks hosted by Notion. - Use Case: After a meeting, ask the agent to create a new Notion page under your team workspace with the meeting notes formatted as headings, bullet lists, and a callout, then update the project database entry's status to Done. ## Quick Start Set your NOTION_API_KEY environment variable and ask the agent to search your Notion workspace for a page and summarize its contents as Markdown.

Frequently Asked Questions about notion

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Notion page from Markdown using the API?

Send a POST request to /v1/pages with a parent page_id, title property, and a markdown body field containing your content. With the ntn CLI, use ntn api v1/pages with the same parameters in shorthand syntax.

How do I query a Notion database with filters?

In API version 2025-09-03, databases are queried as data sources via POST /v1/data_sources/{data_source_id}/query with a JSON body containing filter and sorts clauses. Note the data_source_id differs from the database_id used when creating pages.

Does the ntn CLI work on Windows?

No, the ntn CLI currently supports only macOS and Linux, with Windows support planned. Windows users can use curl with the Notion HTTP API directly, or run ntn inside WSL2.

Why does the Notion API return 404 for a page that exists?

The page has not been shared with your integration. In Notion, open the page menu, select Connect to, and add your integration. Without this step the API cannot see the page even with a valid token.

How do I upload files to Notion through the API?

With ntn, run ntn files create < file for a one-line upload. Over HTTP it takes three steps: create a file upload via POST /v1/file_uploads, PUT the bytes to the returned upload_url, then reference the file_upload_id in a page or block payload.

What are the limitations of Notion Workers?

Deploying Workers requires a Notion Business or Enterprise plan and the ntn CLI, which is macOS/Linux only. Workers are free through August 11, 2026, after which usage is metered on Notion credits.