Notion
以兩種方式與 Notion 對話。兩者使用相同的整合令牌——根據環境選擇適合的方式。
◆ ntn CLI — Notion 官方 CLI。語法更簡潔,可一行指令上傳檔案,Workers 的必要工具。截至 2026 年 5 月僅支援 macOS + Linux(Windows 支援「即將推出」)。已安裝時為預設選項。
◆ HTTP + curl — 適用於所有平台,包含 Windows。當未安裝 ntn 時的預設備案。
設定
1. 取得整合令牌(兩種路徑皆需)
- 在 https://notion.so/my-integrations 建立整合
- 複製 API 金鑰(開頭為
ntn_或secret_) - 儲存至
~/.hermes/.env:NOTION_API_KEY=ntn_your_key_here - 在 Notion 中與整合分享目標頁面/資料庫:頁面選單
...→連線到→ 你的整合名稱。缺少此步驟時,API 即使頁面存在也會回傳 404。
2. 安裝 ntn(macOS / Linux 首選路徑)
# 建議
curl -fsSL https://ntn.dev | bash
# 或透過 npm(需要 Node 22+、npm 10+)
npm install --global ntn
ntn --version # 驗證
跳過 ntn login — 直接使用整合令牌。 此方式可無瀏覽器執行:
export NOTION_API_TOKEN=$NOTION_API_KEY # ntn 讀取 NOTION_API_TOKEN
export NOTION_KEYRING=0 # 不嘗試使用作業系統鑰匙圈
將這些匯出指令加入你的 shell profile(或 ~/.hermes/.env),讓每個工作階段都能繼承它們。
3. 執行階段選擇路徑
if command -v ntn >/dev/null 2>&1; then
# 使用 ntn
else
# 備案使用 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
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;:= 用於非字串型別(布林/數字/null)
語法說明:
key=value— 字串欄位key[nested]=value— 巢狀物件欄位key:=value— 型別指定(布林值、數字、null、陣列)
搜尋
ntn api v1/search query="page title"
讀取頁面中繼資料
ntn api v1/pages/{page_id}
以 Markdown 讀取頁面(代理友善)
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\n\n- Q3 roadmap\n- Hiring"
以 Markdown 更新頁面
ntn api v1/pages/{page_id}/markdown -X PATCH \
markdown="## Update\n\nShipped 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 流程需要三個步驟(建立上傳 → 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 讀取頁面(代理友善)
比區塊 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!"}}]}}
]
}'
檔案上傳(三步驟流程)
# 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 至上一步回傳的 upload_url
curl -s -X PUT "{upload_url}" --data-binary @photo.png
# 3. 在頁面/區塊負載中引用 {file_upload_id}
屬性型別
資料庫項目的常見屬性格式:
- 標題:
{"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": "https://..."} - 電子郵件:
{"email": "[email protected]"} - 關聯:
{"relation": [{"id": "page_id"}]}
API 版本 2025-09-03 — 資料庫 vs 資料來源
- 資料庫已改稱為資料來源。 查詢和擷取請使用
/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)
Workers 是 Notion 為你代管的 TypeScript 程式。一個 Worker 可以組合暴露以下任何功能:
- 同步 — 依排程(預設 30 分鐘)從外部 API 拉取資料至 Notion 資料庫。
- 工具 — 在 Notion 的自訂代理中顯示為可呼叫工具。
- Webhook — 從外部服務(GitHub、Stripe 等)接收 HTTP 事件並在 Notion 中執行操作。
方案/平台限制:
- CLI 適用於所有方案。部署 Workers 需要 Business 或 Enterprise 方案。
- 截至 2026 年 5 月,
ntn僅支援 macOS/Linux。Windows 使用者需要 WSL2 或等候原生支援。 - 至 2026 年 8 月 11 日免費;之後按 Notion 點數計費。
最小 Worker 範例
ntn workers new my-worker # 建立 scaffold
cd my-worker
# 編輯 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(用於簽章驗證), event.headers
console.log("got delivery", event.deliveryId);
}
},
});
部署後:ntn workers webhooks list 會顯示 Notion 產生的網址。請將此網址視為機密——任何知道它的人都可以 POST 事件,除非你加入簽章驗證。
Worker 生命週期指令
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 建立 scaffold,在 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>
子內容縮排一個定位點
</details>
<columns>
<column>左側</column>
<column>右側</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>。
選擇正確的路徑
| 任務 | macOS / Linux | Windows |
|---|---|---|
| 讀寫頁面、搜尋、查詢資料庫 | ntn api ... | curl |
| 讀取頁面以供代理總結 | ntn api v1/pages/{id}/markdown | curl /markdown 端點 |
| 上傳檔案 | ntn files create < file | 三步驟 HTTP 流程 |
| 一次性 API 探索 | ntn api ... | curl |
| 建立由 Notion 代管的同步/Webhook/代理工具 | ntn workers ... | WSL2 + ntn workers ... |
注意事項
- 頁面/資料庫 ID 為 UUID(可含或不含連字號——兩者皆可接受)。
- 速率限制:約 3 請求/秒平均。CLI 不會繞過此限制。
- API 無法設定資料庫檢視篩選條件——此為 UI 專屬功能。
- 建立資料來源時使用
"is_inline": true可將其嵌入頁面中。 - 始終對 curl 傳入
-s以抑制進度條(更乾淨的代理輸出)。 - 讀取時可透過管道將 JSON 傳入
jq:... | jq '.results[0].properties'。 - Notion 現在也提供 MCP 伺服器
…
[因翻譯而截斷]