notion

Notion

通过两种方式与 Notion 交互。两种方式都使用相同的集成令牌——根据可用方式选择即可。

◆ ntn CLI — Notion 官方 CLI。语法更简洁，可用一行命令上传文件，Workers 必须使用此方式。截至 2026 年 5 月，仅支持 macOS 和 Linux（Windows 支持“即将推出”）。安装后默认使用。 ◆ HTTP + curl — 适用于所有平台，包括 Windows。未安装 ntn 时的默认备用方式。

设置

1. 获取集成令牌（两种方式都需要）

1. 在 https://notion.so/my-integrations 创建集成
2. 复制 API 密钥（以 ntn_ 或 secret_ 开头）
3. 存储在 ${HERMES_HOME:-~/.hermes}/.env 中：

   NOTION_API_KEY=ntn_your_key_here
   

4. 在 Notion 中将目标页面／数据库共享给此集成：打开页面菜单 ... → Connect to → 选择你的集成名称。如果不这样做，即使页面存在，API 也会对该页面返回 404。

2. 安装 ntn（macOS / Linux 上的首选方式）

# Recommended
curl -fsSL https://ntn.dev | bash

# Or via npm (needs Node 22+, npm 10+)
npm install --global ntn

ntn --version    # verify

跳过 ntn login，改用集成令牌。 此方式可在无头环境中使用，无需浏览器：

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN
export NOTION_KEYRING=0                       # don't try to use the OS keychain

将这些导出命令添加到 shell 配置文件（或 ${HERMES_HOME:-~/.hermes}/.env），以便每个会话都能继承这些变量。

3. 运行时选择方式

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

Windows 用户：在原生 ntn 发布前，完全跳过步骤 2——路径 B 可以正常使用。如果现在就想使用 CLI 的便捷体验，可以在 WSL2 中安装 ntn。

API 基础知识

所有 HTTP 请求都必须包含 Notion-Version: 2025-09-03。ntn 会为你处理此项。在此版本中，用户所说的“数据库”在 API 中称为数据源。

路径 A — ntn CLI（首选，macOS / Linux）

原始 API 调用（curl 的简写）

ntn api v1/users                                  # GET
# POST with inline body
ntn api v1/pages parent[page_id]=abc123 \
  properties[title][0][text][content]="Notes"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH; := is non-string (bool/num/null)

语法说明：

• key=value — 字符串字段
• key[nested]=value — 嵌套对象字段
• key:=value — 带类型的赋值（布尔值、数字、null、数组）

搜索

ntn api v1/search query="page title"

读取页面元数据

ntn api v1/pages/{page_id}

将页面读取为 Markdown（便于 Agent 使用）

ntn api v1/pages/{page_id}/markdown

将页面内容读取为块

ntn api v1/blocks/{page_id}/children

根据 Markdown 创建页面

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Notes from meeting" \
  markdown="# Agenda

- Q3 roadmap
- Hiring"

使用 Markdown 更新页面

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## Update

Shipped the prototype."

查询数据库（数据源）

ntn api v1/data_sources/{data_source_id}/query -X POST \
  filter[property]=Status filter[select][equals]=Active

对于包含 sorts、多个筛选条件或复合逻辑的复杂查询，可通过管道传入 JSON：

echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
  ntn api v1/data_sources/{data_source_id}/query -X POST --json -

文件上传（一行命令 — CLI 的最大优势）

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

相比之下，HTTP 流程需要 3 个步骤（创建上传 → PUT 字节数据 → 引用）。

常用环境变量

变量	作用
NOTION_API_TOKEN	身份验证令牌（覆盖密钥链）——将其设置为你的集成令牌
NOTION_KEYRING=0	使用文件凭据 ~/.config/notion/auth.json，而非操作系统密钥链
NOTION_WORKSPACE_ID	跳过工作区选择提示

路径 B — HTTP + curl（跨平台，Windows 上默认使用）

所有请求都遵循以下模式：

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"

在 Windows 上，Windows 10 及更高版本自带的 curl 可以直接使用。PowerShell 用户也可以使用 Invoke-RestMethod。

搜索

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"}'

读取页面元数据

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

将页面读取为 Markdown（便于 Agent 使用）

相比块 JSON，更容易提供给模型。

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

将页面内容读取为块（需要结构化内容时）

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

根据 Markdown 创建页面

POST /v1/pages 接受 markdown 正文参数。

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"
  }'

使用 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."}'

在数据库中创建页面（带类型的属性）

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"}}
    }
  }'

查询数据库（数据源）

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"}]
  }'

创建数据库

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": {}}
    }
  }'

更新页面属性

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"}}}}'

向页面追加块

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!"}}]}}
    ]
  }'

文件上传（3 步流程）

# 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

属性类型

数据库条目的常见属性格式：

• 标题： {"title": [{"text": {"content": "..."}}]}
• 富文本： {"rich_text": [{"text": {"content": "..."}}]}
• 单选： {"select": {"name": "Option"}}
• 多选： {"multi_select": [{"name": "A"}, {"name": "B"}]}
• 日期： {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
• 复选框： {"checkbox": true}
• 数字： {"number": 42}
• URL： {"url": "https://..."}
• 电子邮件： {"email": "[email protected]"}
• 关联： {"relation": [{"id": "page_id"}]}

API 版本 2025-09-03 — 数据库与数据源

• 数据库现已成为数据源。 使用 /data_sources/ 端点进行查询和检索。
• 每个数据库有两个 ID： database_id 和 data_source_id。
  • 创建页面时使用 database_id：parent: {"database_id": "..."}
  • 查询时使用 data_source_id：POST /v1/data_sources/{id}/query
• 搜索结果会将数据库作为 "object": "data_source" 返回，并包含 data_source_id 字段。

Notion Workers（高级功能，需要 ntn）

Worker 是 Notion 为你托管的 TypeScript 程序。一个 Worker 可以公开以下任意组合：

• 同步任务 — 按计划（默认每 30 分钟）从外部 API 拉取数据到 Notion 数据库。
• 工具 — 可在 Notion 的 Custom Agents 中作为可调用工具使用。
• Webhook — 接收来自外部服务（GitHub、Stripe 等）的 HTTP 事件，并在 Notion 中执行操作。

套餐／平台限制：

• 所有套餐均可使用 CLI。部署 Worker 需要 Business 或 Enterprise 套餐。
• 截至 2026 年 5 月，ntn 仅支持 macOS/Linux。Windows 用户需要使用 WSL2，或等待原生支持。
• 截至 2026 年 8 月 11 日免费；之后按 Notion credits 计量收费。

最小 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 功能

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);
    }
  },
});

部署后：ntn workers webhooks list 会显示 Notion 生成的 URL。请将该 URL 视为机密信息——除非你添加签名验证，否则任何知道该 URL 的人都可以 POST 事件。

Worker 生命周期命令

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

当需要构建 Worker 时，使用 ntn workers new 搭建项目框架，在 src/index.ts 中编写代码，使用 ntn workers env set 设置所需密钥，然后部署。Notion 文档 https://developers.notion.com/workers 涵盖了完整的 API 功能。

Notion 风格的 Markdown（由 /markdown 端点使用）

标准 CommonMark，外加用于 Notion 专属块的类 XML 标签。缩进请使用制表符。

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"/>

行内内容：

• 提及：<mention-user url="..."/>、<mention-page url="...">Title</mention-page>、<mention-date start="2026-05-15"/>
• 下划线：<span underline="true">text</span>
• 颜色：<span color="blue">text</span>，或在首行使用块级 {color="blue"}
• 数学公式：行内 $x^2$，块级 $$ ... $$
• 引用：[^https://example.com]

颜色： gray brown orange yellow green blue purple pink red，以及用于背景的 *_bg 变体。

标题 5/6 会折叠为 H4。多个 > 行会呈现为独立的引用块——如需多行引用，请在单个 > 内使用 <br>。

选择合适的方式

任务	mac / Linux	Windows
读取／写入页面、搜索、查询数据库	ntn api ...	curl
读取页面以供 Agent 总结	ntn api v1/pages/{id}/markdown	curl /markdown 端点
上传文件	ntn files create < file	3 步 HTTP 流程
一次性 API 探索	ntn api ...	curl
构建由 Notion 托管的同步任务／Webhook／Agent 工具	ntn workers ...	WSL2 + ntn workers ...

备注

• 页面／数据库 ID 为 UUID（带或不带连字符均可）。
• 速率限制：平均每秒约 3 个请求。CLI 无法绕过此限制。
• API 无法设置数据库的视图筛选条件——这只能通过 UI 操作。
• 创建数据源时使用 "is_inline": true，将其嵌入页面。
• 使用 curl 时始终传入 -s 以隐藏进度条（让 Agent 输出更整洁）。
• 读取 JSON 时通过 jq 处理：... | jq '.results[0].properties'。
• Notion 现在也提供了 MCP 服务（Notion MCP，在数据库操作上比上一版本节省约 91% 的 token）——如果你想在会话内流式访问 Notion，可通过 Hermes 的 MCP 支持接入；不过，对于大多数一次性任务来说，上述方式已经足够。