notion

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

Updated Aug 22, 2026
One-click install
npx skills add https://github.com/vivekgoquest/hermes-agent-stable --skill notion-vivekgoquest
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: notion
Source: https://github.com/vivekgoquest/hermes-agent-stable/tree/main/skills/productivity/notion
Command: npx skills add https://github.com/vivekgoquest/hermes-agent-stable --skill notion-vivekgoquest

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Working with Notion programmatically requires juggling API versioning, block JSON structures, database query syntax, and multi-step file uploads. This Skill provides ready-to-use commands for both the official ntn CLI and the cross-platform curl-based HTTP API, so you can read, create, 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 syntax and one-line file uploads, with automatic fallback to curl on Windows or when ntn is not installed. - Full content management: 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 TypeScript Workers that host syncs, agent tools, and webhooks inside Notion (Business/Enterprise plans). - Use Case: After a meeting, ask the agent to create a new page under your team workspace with the agenda and decisions written 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 create a Notion page titled "Meeting Notes" with a Markdown summary of today's discussion.

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 parameter containing your content. With the ntn CLI installed, run ntn api v1/pages with inline parent, properties, and markdown fields for shorter 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 filter and optional sorts. Note that creating pages still uses database_id in the parent field, while querying uses data_source_id.

Does the ntn CLI work on Windows?▼

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

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

A 404 occurs when the page or database has not been shared with your integration. In Notion, open the page menu, select Connect to, and choose your integration name so the API token gains access.

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 is a three-step flow: POST /v1/file_uploads to create an upload, 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?▼

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