Notion via Hermes Agent: CLI, HTTP API, and Workers Guide

This guide covers two ways to talk to Notion from Hermes Agent: the ntn CLI (macOS/Linux) and plain HTTP with curl (cross-platform). Both use the same integration token, so you can pick whichever fits your environment. You will learn how to read and write pages, query databases, upload files, and deploy Notion Workers.

What it does

You can automate Notion operations directly from your terminal or from within a Hermes Agent workflow. The ntn CLI gives you a shorter syntax and one-line file uploads, while the HTTP+curl path works everywhere, including Windows. Both paths let you search pages, read content as Markdown (ideal for feeding to a language model), create and update pages, query databases, and manage file attachments. The Workers feature (requires ntn) lets you deploy TypeScript programs that Notion hosts, exposing syncs, tools, and webhooks.

Before you start

You need a Notion integration token. Create one at https://notion.so/my-integrations. The token starts with ntn_ or secret_. Store it in ${HERMES_HOME:-~/.hermes}/.env:

NOTION_API_KEY=ntn_your_key_here

You must also share each target page or database with the integration. In Notion, open the page menu (...), choose Connect to, and select your integration. Without this step, the API returns 404 for that page even though it exists.

For the ntn CLI (preferred on macOS and Linux), install it:

# 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 directly. 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.

At runtime, choose the path:

if command -v ntn >/dev/null 2>&1; then
  # use ntn
else
  # fall back to curl
fi

Windows users: skip the ntn install entirely until native ntn ships. The curl path works fine. If you want CLI ergonomics now, install ntn inside WSL2.

API Basics

All HTTP requests require the header Notion-Version: 2025-09-03. The ntn CLI 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"}}
• Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
• Date: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
• Checkbox: {"checkbox": true}
• Number: {"number": 42}
• URL: {"url": "https://..."}
• Email: {"email": "user@example.com"}
• Relation: {"relation": [{"id": "page_id"}]}

API Version 2025-09-03, Databases vs Data Sources

• Databases became data sources. Use /data_sources/ endpoints for queries and retrieval.

• Two IDs per database: database_id and data_source_id.

  • database_id when creating pages: parent: {"database_id": "..."}
  • data_source_id when querying: POST /v1/data_sources/{id}/query

• Search returns databases as "object": "data_source" with the data_source_id field.

Notion Workers (advanced, requires ntn)

Workers are TypeScript programs Notion hosts for you. One worker can expose any combination of:

• Syncs, pull data from external APIs into a Notion database on a schedule (default 30 min).
• Tools, appear as callable tools inside Notion's Custom Agents.
• Webhooks, receive HTTP events from external services (GitHub, Stripe, etc.) and act in Notion.

Plan / platform gating:

• CLI works on all plans. Deploying Workers requires Business or Enterprise.
• ntn is macOS/Linux only as of May 2026. Windows users need WSL2 or to wait for native support.
• Free through August 11, 2026; metered on Notion credits after.

Minimal Worker

ntn workers new my-worker      # scaffold
cd my-worker
# Edit src/index.ts
ntn workers deploy --name my-worker

src/index.ts:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("greet", {
  title: "Greet a User",
  description: "Returns a friendly greeting",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `Hello, ${name}!`,
});

Webhook capability

worker.webhook("onGithubPush", {
  title: "GitHub Push Handler",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody (for signature verification), event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

After deploy: ntn workers webhooks list shows the URL Notion generates. Treat that URL as a secret, anyone with it can POST events unless you add signature verification.

Worker lifecycle commands

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # run a sync now
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # recent invocations
ntn workers runs logs <run-id>
ntn workers webhooks list

When asked to build a Worker, scaffold with ntn workers new, write the code in src/index.ts, set any secrets with ntn workers env set, and deploy. Notion's docs at https://developers.notion.com/workers cover the full API surface.

Notion-Flavored Markdown (used by /markdown endpoints)

Standard CommonMark plus XML-like tags for Notion-specific blocks. Use tabs for indentation.

Blocks beyond CommonMark:

<callout icon="🎯" color="blue_bg">
	Ship the MVP by **Friday**.
</callout>

<details color="gray">
<summary>Toggle title</summary>
	Children indented one tab
</details>

<columns>
	<column>Left side</column>
	<column>Right side</column>
</columns>

<table_of_contents color="gray"/>

Inline:

• Mentions: , `Title`,
• Underline: text
• Color: text or block-level {color="blue"} on the first line
• Math: inline $x^2$, block $$ ... $$
• Citations: [^https://example.com]

Colors: gray brown orange yellow green blue purple pink red, plus *_bg variants for backgrounds.

Headings 5/6 collapse to H4. Multiple > lines render as separate quote blocks, use inside a single > for multi-line quotes.

Choosing the Right Path

Task	mac / Linux	Windows
Read/write pages, search, query databases	ntn api ...	curl
Read a page for an agent to summarize	ntn api v1/pages/{id}/markdown	curl /markdown endpoint
Upload a file	ntn files create < file	3-step HTTP flow
One-off API exploration	ntn api ...	curl
Build a sync / webhook / agent tool hosted by Notion	ntn workers ...	WSL2 + ntn workers ...

Notes

• Page/database IDs are UUIDs (with or without dashes, both accepted).
• Rate limit: ~3 requests/second average. The CLI doesn't bypass this.
• The API cannot set database view filters, that's UI-only.
• Use "is_inline": true when creating data sources to embed them in a page.
• Always pass -s to curl to suppress progress bars (cleaner agent output).
• Pipe JSON through jq when reading: ... | jq '.results[0].properties'.
• Notion also ships an MCP server now (Notion MCP, ~91% more token-efficient on DB ops than the previous version), wire it via Hermes' MCP support if you want streaming Notion access from inside a session, but the paths above are enough for most one-shot tasks.

When not to use it

If you need to set database view filters or perform complex UI-only operations, the API cannot help. For streaming Notion access inside a session, consider the Notion MCP server instead.

Limits and gotchas

The rate limit is about 3 requests per second. The CLI does not bypass this. The API cannot set database view filters. Page/database IDs are UUIDs (with or without dashes). Always share target pages/databases with your integration before using them, or you will get 404 errors.

What pairs with this

• Notion MCP server for streaming access inside a session.
• Hermes Agent's MCP support for wiring Notion MCP.
• Notion's official Workers documentation at https://developers.notion.com/workers.