notion

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

1|Updated Jun 24, 2026
One-click install
npx skills add https://github.com/maopujie10-sys/Bailongma --skill notion-maopujie10-sys
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: notion
Source: https://github.com/maopujie10-sys/Bailongma/tree/main/skills/hermes-skills/productivity/notion
Command: npx skills add https://github.com/maopujie10-sys/Bailongma --skill notion-maopujie10-sys

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Working with Notion programmatically requires juggling API versions, authentication tokens, block JSON structures, and multi-step file uploads. This Skill provides ready-to-use commands for both the official ntn CLI and plain curl, so you can read, create, search, and update Notion content without memorizing the API surface. ## Core Features & Use Cases - Dual-path operation: Uses the ntn CLI on macOS/Linux for short commands and one-line file uploads, with a curl-based HTTP fallback that works everywhere including Windows. - Full content workflow: Search workspaces, read pages as agent-friendly Markdown, create and patch pages from Markdown, query data sources with filters and sorts, and upload files. - Notion Workers: Scaffold, deploy, and manage hosted TypeScript Workers that run syncs, expose agent tools, and receive webhooks (Business/Enterprise plans). - Use Case: After a meeting, ask the agent to create a new page under your team workspace with the meeting notes in Markdown, then query your tasks database for all items with Status "Active" sorted by date. ## Quick Start Set NOTION_API_KEY in your environment, share the target pages with your integration, then ask the agent to search Notion for a page and read it 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 via 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 inline parent, properties, and markdown parameters.

How do I query a Notion database with filters?

In API version 2025-09-03, databases are data sources, so POST to /v1/data_sources/{data_source_id}/query with a filter object like {"property": "Status", "select": {"equals": "Active"}} and optional sorts. Complex queries can be piped as JSON to the ntn CLI.

Does the ntn CLI work on Windows?

The ntn CLI is macOS and Linux only as of May 2026, with Windows support planned. Windows users can use the curl-based HTTP path directly, or install ntn inside WSL2 for CLI ergonomics.

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, choose Connect to, and select your integration name. 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 < photo.png 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 Notion Workers and what plan do they require?

Workers are TypeScript programs hosted by Notion that provide scheduled syncs, agent tools, and webhook handlers. The CLI works on all plans, but deploying Workers requires a Business or Enterprise plan and the ntn CLI on macOS or Linux.