notion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

与Notion交互有两种方式。同一个集成令牌适用于两种方式——根据可用情况选择即可。

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

Setup

配置步骤

1. Get an integration token (required for both paths)

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

Create an integration at https://notion.so/my-integrations
Copy the API key (starts with
```
ntn_
```
or
```
secret_
```
)

Store in

~/.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.

在https://notion.so/my-integrations创建集成
复制API密钥（以
```
ntn_
```
或
```
secret_
```
开头）

将其存储在

~/.hermes/.env

中：

NOTION_API_KEY=ntn_your_key_here

在Notion中将目标页面/数据库共享给该集成：页面菜单
```
...
```
→
```
Connect to
```
→ 你的集成名称。如果不这么做，即使页面存在，API也会返回404错误。

2. Install

ntn

(preferred path on macOS / Linux)

2. 安装

ntn

（macOS / Linux推荐方式）

bash

undefined

bash

undefined

Or via npm (needs Node 22+, npm 10+)

或通过npm安装（需要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:
```bash
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/.env

) so every session inherits them.

npm install --global ntn

ntn --version # 验证安装


**跳过`ntn login`——直接使用集成令牌。** 此方式无需浏览器，可无头运行：
```bash
export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn会读取NOTION_API_TOKEN
export NOTION_KEYRING=0                       # 不尝试使用系统密钥链

将这些环境变量添加到你的shell配置文件（或

~/.hermes/.env

）中，以便每个会话都能继承它们。

3. Choose path at runtime

3. 运行时选择交互方式

bash

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.

bash

if command -v ntn >/dev/null 2>&1; then
  # 使用ntn
else
  # 回退到curl
fi

Windows用户：在原生

ntn

发布前完全跳过步骤2——方式B可以正常工作。如果现在就想使用CLI的便捷性，可以在WSL2中安装

ntn

。

API Basics

API基础

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.

所有HTTP请求都必须携带

Notion-Version: 2025-09-03

。

ntn

会自动处理此头部。在该版本中，用户所说的“databases”在API中被称为data sources。

Path A —

ntn

CLI (preferred, macOS / Linux)

方式A —

ntn

CLI（推荐，macOS / Linux）

Raw API calls (shorthand for curl)

原始API调用（curl的简写形式）

bash

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)

bash

ntn api v1/users                                  # GET请求
ntn api v1/pages parent[page_id]=abc123 \         # 带内嵌请求体的POST请求
  properties[title][0][text][content]="Notes"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH请求；:=用于非字符串类型（布尔/数字/空值）

语法说明：

```
key=value
```
— 字符串字段
```
key[nested]=value
```
— 嵌套对象字段
```
key:=value
```
— 类型化赋值（布尔值、数字、空值、数组）

Search

搜索

bash

ntn api v1/search query="page title"

bash

ntn api v1/search query="page title"

Read page metadata

读取页面元数据

bash

ntn api v1/pages/{page_id}

bash

ntn api v1/pages/{page_id}

Read page as Markdown (agent-friendly)

将页面读取为Markdown格式（适合Agent使用）

bash

ntn api v1/pages/{page_id}/markdown

bash

ntn api v1/pages/{page_id}/markdown

Read page content as blocks

将页面内容读取为blocks

bash

ntn api v1/blocks/{page_id}/children

bash

ntn api v1/blocks/{page_id}/children

Create page from Markdown

从Markdown创建页面

bash

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

- Q3 roadmap
- Hiring"

bash

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

用Markdown更新页面

bash

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

Shipped the prototype."

bash

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

Shipped the prototype."

Query a database (data source)

查询数据库（data source）

bash

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:

bash

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

bash

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

对于包含

sorts

、多个过滤条件或复合逻辑的复杂查询，可通过管道传入JSON：

bash

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)

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

bash

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).

bash

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

相比之下，HTTP方式需要三步流程（创建上传任务 → 上传字节数据 → 引用文件）。

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

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

Path B — HTTP + curl (cross-platform, default on Windows)

方式B — HTTP + curl（跨平台，Windows默认方式）

All requests share this pattern:

bash

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

所有请求遵循以下模式：

bash

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 10+自带的

curl

可直接使用。PowerShell用户也可以使用

Invoke-RestMethod

。

Search

搜索

bash

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

bash

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

读取页面元数据

bash

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

bash

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)

将页面读取为Markdown格式（适合Agent使用）

Easier to feed to a model than block JSON.

bash

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

相比block JSON格式，此格式更容易输入到模型中。

bash

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)

将页面内容读取为blocks（需要结构化数据时使用）

bash

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

bash

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

从Markdown创建页面

POST /v1/pages

accepts a

markdown

body param.

bash

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

POST /v1/pages

请求接受

markdown

请求体参数。

bash

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

用Markdown更新页面

bash

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

bash

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)

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

bash

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

bash

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)

查询数据库（data source）

bash

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

bash

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

创建数据库

bash

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

bash

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

更新页面属性

bash

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

bash

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

向页面追加blocks

bash

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

bash

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)

文件上传（三步流程）

bash

undefined

bash

undefined

1. Create upload

1. 创建上传任务

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

2. 将字节数据PUT到上述返回的upload_url

curl -s -X PUT "{upload_url}" --data-binary @photo.png

3. Reference {file_upload_id} in a page/block payload

3. 在页面/block的请求体中引用{file_upload_id}

undefined

undefined

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

数据库项的常见属性格式：

标题（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

API版本2025-09-03 — Databases与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.

Databases更名为data sources。查询和检索时使用
```
/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 (advanced, requires

ntn

)

Notion Workers（高级功能，需要

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.

Workers是Notion为你托管的TypeScript程序。一个Worker可以同时提供以下任意组合的功能：

同步（Syncs） — 按计划（默认30分钟）从外部API拉取数据到Notion数据库。
工具（Tools） — 在Notion自定义Agent中作为可调用工具出现。
Webhooks — 接收来自外部服务（GitHub、Stripe等）的HTTP事件并在Notion中执行操作。

计划/平台限制：

CLI适用于所有计划。部署Workers需要Business或Enterprise计划。
截至2026年5月，
```
ntn
```
仅支持macOS/Linux。Windows用户需要使用WSL2或等待原生支持。
2026年8月11日前免费；之后按Notion credits计费。

Minimal Worker

最简Worker示例

bash

ntn workers new my-worker      # scaffold
cd my-worker

bash

ntn workers new my-worker      # 生成脚手架
cd my-worker

Edit src/index.ts

编辑src/index.ts

ntn workers deploy --name my-worker


`src/index.ts`:
```typescript
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}!`,
});

ntn workers deploy --name my-worker


`src/index.ts`:
```typescript
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

Webhook功能

typescript

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.

typescript

worker.webhook("onGithubPush", {
  title: "GitHub Push Handler",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody（用于签名验证）, event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

部署后：

ntn workers webhooks list

会显示Notion生成的URL。请将该URL视为机密——除非添加签名验证，否则任何人都可以通过它发送POST事件。

Worker lifecycle commands

Worker生命周期命令

bash

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.

bash

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # 立即运行一次同步
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # 最近的调用记录
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-Flavored Markdown (used by

/markdown

endpoints)

Notion风格Markdown（

/markdown

端点使用）

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:

<mention-user url="..."/>

<mention-page url="...">Title</mention-page>

<mention-date start="2026-05-15"/>

Underline:
```
<span underline="true">text</span>
```

Color:

<span color="blue">text</span>

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

<br>

inside a single

for multi-line quotes.

基于标准CommonMark，添加了XML风格标签用于Notion特定块。使用制表符进行缩进。

超出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级标题会折叠为4级标题。多行

会渲染为独立的引用块——如需多行引用，请在单个

内使用

<br>

。

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 ...`

任务	mac / Linux	Windows
读写页面、搜索、查询数据库	`ntn api ...`	curl
读取页面供Agent总结	`ntn api v1/pages/{id}/markdown`	curl调用 `/markdown` 端点
上传文件	`ntn files create < file`	三步HTTP流程
一次性API探索	`ntn api ...`	curl
构建由Notion托管的同步/Webhook/Agent工具	`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.

页面/数据库ID是UUID（带或不带连字符均可接受）。
速率限制：平均约3请求/秒。CLI无法绕过此限制。
API无法设置数据库视图过滤器——这是仅UI端的功能。
创建data sources时使用
```
"is_inline": true
```
可将其嵌入页面。
使用curl时始终加上
```
-s
```
参数以抑制进度条（使Agent输出更整洁）。
读取JSON时可通过管道传递给
```
jq
```
：
```
... | jq '.results[0].properties'
```
。
Notion现在还推出了MCP服务器（
```
Notion MCP
```
，相比之前版本，数据库操作的令牌效率提升约91%）——如果你想在会话内流式访问Notion，可以通过Hermes的MCP支持连接，但上述方式足以满足大多数一次性任务。

notion

Original

Translation

Notion

Notion

Setup

配置步骤

1. Get an integration token (required for both paths)

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

2. Install ntn (preferred path on macOS / Linux)

2. 安装ntn（macOS / Linux推荐方式）

Recommended

推荐方式

Or via npm (needs Node 22+, npm 10+)

或通过npm安装（需要Node 22+，npm 10+）

3. Choose path at runtime

3. 运行时选择交互方式

API Basics

API基础

Path A — ntn CLI (preferred, macOS / Linux)

方式A — ntn CLI（推荐，macOS / Linux）

Raw API calls (shorthand for curl)

原始API调用（curl的简写形式）

Search

搜索

Read page metadata

读取页面元数据

Read page as Markdown (agent-friendly)

将页面读取为Markdown格式（适合Agent使用）

Read page content as blocks

将页面内容读取为blocks

Create page from Markdown

从Markdown创建页面

Patch a page with Markdown

用Markdown更新页面

Query a database (data source)

查询数据库（data source）

File uploads (one-liner — biggest CLI win)

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

Useful env vars

实用环境变量

Path B — HTTP + curl (cross-platform, default on Windows)

方式B — HTTP + curl（跨平台，Windows默认方式）

Search

搜索

Read page metadata

读取页面元数据

Read page as Markdown (agent-friendly)

将页面读取为Markdown格式（适合Agent使用）

Read page content as blocks (when you need structure)

将页面内容读取为blocks（需要结构化数据时使用）

Create page from Markdown

从Markdown创建页面

Patch a page with Markdown

用Markdown更新页面

Create page in a database (typed properties)

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

Query a database (data source)

查询数据库（data source）

Create a database

创建数据库

Update page properties

更新页面属性

Append blocks to a page

向页面追加blocks

File uploads (3-step flow)

文件上传（三步流程）

1. Create upload

1. 创建上传任务

2. PUT bytes to the upload_url returned above

2. 将字节数据PUT到上述返回的upload_url

3. Reference {file_upload_id} in a page/block payload

3. 在页面/block的请求体中引用{file_upload_id}

Property Types

属性类型

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

API版本2025-09-03 — Databases与Data Sources的区别

Notion Workers (advanced, requires ntn)

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

Minimal Worker

2. Install
`ntn`
(preferred path on macOS / Linux)

2. 安装
`ntn`
（macOS / Linux推荐方式）

Path A —
`ntn`
CLI (preferred, macOS / Linux)

方式A —
`ntn`
CLI（推荐，macOS / Linux）

Notion Workers (advanced, requires
`ntn`
)

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

Notion-Flavored Markdown (used by
`/markdown`
endpoints)

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