notion

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

Updated Jun 5, 2026
One-click install
npx skills add https://github.com/xu1713/openhorse --skill notion-xu1713
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: notion
Source: https://github.com/xu1713/openhorse/tree/main/openhorse/openhorse/skills/productivity/notion
Command: npx skills add https://github.com/xu1713/openhorse --skill notion-xu1713

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Working with Notion programmatically requires juggling API versions, block JSON structures, file upload flows, and platform-specific tooling. This Skill provides ready-to-use commands for both the official ntn CLI and plain curl, so you can read, create, and update Notion content from any platform without memorizing the API surface. ## Core Features & Use Cases - Dual-path operation: Uses the ntn CLI on macOS/Linux for short syntax and one-line file uploads, with a curl-based HTTP fallback that works everywhere including Windows. - Full content workflow: Search workspaces, read pages as Markdown or blocks, 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 Notion page from your Markdown notes under a specific parent page, then query a tasks database for all items with Status "Active" sorted by date. ## Quick Start Set NOTION_API_KEY in your environment, share the target page with your integration, then ask the agent to read a Notion page as Markdown or create a new page from your notes.

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, a title property, and a markdown body field containing your content. With the ntn CLI, use ntn api v1/pages with the same fields as inline key=value arguments.

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 filter and optional sorts. Note that creating pages still uses database_id while querying uses data_source_id.

Does the ntn CLI work on Windows?

No, ntn currently supports macOS and Linux only, with Windows support planned. Windows users can use the curl-based HTTP API path 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. Open the page menu in Notion, choose Connect to, and select your integration; without this step the API cannot see the page even with a valid token.

How do I upload a file to Notion through the API?

With ntn, run ntn files create < file for a one-step upload. Over HTTP it takes three steps: create a file_upload object, 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 can run scheduled syncs, expose tools to Custom Agents, and receive webhooks. Deploying them requires a Business or Enterprise plan and the ntn CLI.