notion

name notion description Notion API + ntn CLI: pages, databases, markdown, Workers. version 2.0.0 author community license MIT platforms ["linux","macos","windows"] prerequisites {"env_vars":["NOTION_API_KEY"]} metadata {"hermes":{"tags":["Notion","Productivity","Notes","Database","API","CLI","Workers"],"homepage":"https://developers.notion.com"}} Notion Talk to Notion two ways. Same integration token works for both — pick by what's available. ◆ ntn CLI — Notion's official CLI. Shorter syntax, one-line file uploads, required for Workers. macOS + Linux only as of May 2026 (Windows support "coming soon"). Default when installed. ◆ HTTP + curl — works everywhere including Windows. Default fallback when ntn isn't installed. Setup 1. Get an integration token (required for both paths) Create an integration at https://notion.so/my-integrations Copy the API key (starts with ntn_ or secret_ ) Store in ${HERMES_HOME:-~/.hermes}/.env : NOTION_API_KEY=ntn_your_key_here Share target pages/databases with the integration in Notion: page menu ... → Connect to → your integration name. Without this, the API returns 404 for that page even though it exists. 2. Install ntn (preferred path on macOS / Linux) # Recommended curl -fsSL https://ntn.dev | bash # Or via npm (needs Node 22+, npm 10+) npm install --global ntn ntn --version # verify Skip ntn login — use the integration token instead. This works headlessly, no browser needed: export NOTION_API_TOKEN= $NOTION_API_KEY # ntn reads NOTION_API_TOKEN export NOTION_KEYRING=0 # don't try to use the OS keychain Add those exports to your shell profile (or to ${HERMES_HOME:-~/.hermes}/.env ) so every session inherits them. 3. Choose path at runtime if command -v ntn >/dev/null 2>&1; then # use ntn else # fall back to curl fi Windows users: skip step 2 entirely until native ntn ships — Path B works fine. If you want CLI ergonomics now, install ntn inside WSL2. API Basics Notion-Version: 2025-09-03 is required on all HTTP requests. ntn handles this for you. In this version, what users call "databases" are called data sources in the API. Path A — ntn CLI (preferred, macOS / Linux) Raw API calls (shorthand for curl) ntn api v1/users # GET ntn api v1/pages parent[page_id]=abc123 \ # POST with inline body properties[title][0][text][content]= "Notes" ntn api v1/pages/abc123 -X PATCH archived:= true # PATCH; := is non-string (bool/num/null) Syntax notes: key=value — string fields key[nested]=value — nested object fields key:=value — typed assignment (booleans, numbers, null, arrays) Search ntn api v1/search query= "page title" Read page metadata ntn api v1/pages/{page_id} Read page as Markdown (agent-friendly) ntn api v1/pages/{page_id}/markdown Read page content as blocks ntn api v1/blocks/{page_id}/children Create page from Markdown ntn api v1/pages \ parent[page_id]=xxx \ properties[title][0][text][content]= "Notes from meeting" \ markdown= "# Agenda - Q3 roadmap - Hiring" Patch a page with Markdown ntn api v1/pages/{page_id}/markdown -X PATCH \ markdown= "## Update Shipped the prototype." Query a database (data source) ntn api v1/data_sources/{data_source_id}/query -X POST \ filter[property]=Status filter[ select ][equals]=Active For complex queries with sorts , multiple filter clauses, or compound logic, pipe JSON in: echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \ ntn api v1/data_sources/{data_source_id}/query -X POST --json - File uploads (one-liner — biggest CLI win) ntn files create < photo.png ntn files create --external-url https://example.com/photo.png ntn files list Compare to the 3-step HTTP flow (create upload → PUT bytes → reference). Useful env vars Var Effect NOTION_API_TOKEN Auth token (overrides keychain) — set this to your integration token NOTION_KEYRING=0 File-based creds at ~/.config/notion/auth.json instead of OS keychain NOTION_WORKSPACE_ID Skip the workspace picker prompt Path B — HTTP + curl (cross-platform, default on Windows) All requests share this pattern: curl -s -X GET "https://api.notion.com/v1/..." \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" On Windows the curl shipped with Windows 10+ works as-is. PowerShell users can also use Invoke-RestMethod . Search curl -s -X POST "https://api.notion.com/v1/search" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{"query": "page title"}' Read page metadata curl -s "https://api.notion.com/v1/pages/{page_id}" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" Read page as Markdown (agent-friendly) Easier to feed to a model than block JSON. curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" Read page content as blocks (when you need structure) curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" Create page from Markdown POST /v1/pages accepts a markdown body param. curl -s -X POST "https://api.notion.com/v1/pages" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{ "parent": {"page_id": "xxx"}, "properties": {"title": [{"text": {"content": "Notes from meeting"}}]}, "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday" }' Patch a page with Markdown curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{"markdown": "## Update\n\nShipped the prototype."}' Create page in a database (typed properties) curl -s -X POST "https://api.notion.com/v1/pages" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{ "parent": {"database_id": "xxx"}, "properties": { "Name": {"title": [{"text": {"content": "New Item"}}]}, "Status": {"select": {"name": "Todo"}} } }' Query a database (data source) curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{ "filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}] }' Create a database curl -s -X POST "https://api.notion.com/v1/data_sources" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{ "parent": {"page_id": "xxx"}, "title": [{"text": {"content": "My Database"}}], "properties": { "Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}}, "Date": {"date": {}} } }' Update page properties curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{"properties": {"Status": {"select": {"name": "Done"}}}}' Append blocks to a page curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{ "children": [ {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello from Hermes!"}}]}} ] }' File uploads (3-step flow) # 1. Create upload curl -s -X POST "https://api.notion.com/v1/file_uploads" \ -H "Authorization: Bearer $NOTION_API_KEY " \ -H "Notion-Version: 2025-09-03" \ -H "Content-Type: application/json" \ -d '{"filename": "photo.png", "content_type": "image/png"}' # 2. PUT bytes to the upload_url returned above curl -s -X PUT "{upload_url}" --data-binary @photo.png # 3. Reference {file_upload_id} in a page/block payload Property Types Common property formats for database items: Title: {"title": [{"text": {"content": "..."}}]} Rich text: {"rich_text": [{"text": {"content": "..."}}]} Select: {"select": {"name": "Option"}}