Notion

Notion API，用於通過 curl 創建和管理頁面、數據庫及塊。直接從終端搜索、創建、更新和查詢 Notion 工作區。

技能元數據

來源	捆綁（默認安裝）
路徑	skills/productivity/notion
版本	1.0.0
作者	community
許可證	MIT
標籤	Notion, Productivity, Notes, Database, API

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

Notion API

通過 curl 使用 Notion API 來創建、讀取、更新頁面、數據庫（數據源）和塊。無需額外工具——只需 curl 和一個 Notion API 密鑰。

前提條件

1. 在 https://notion.so/my-integrations 創建集成
2. 複製 API 密鑰（以 ntn_ 或 secret_ 開頭）
3. 將其存儲在 ~/.hermes/.env 中：

   NOTION_API_KEY=ntn_your_key_here

4. 重要： 在 Notion 中與你的集成共享目標頁面/數據庫（點擊“...” → “連接到” → 你的集成名稱）

API 基礎

所有請求均使用以下模式：

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"

Notion-Version 標頭是必需的。此技能使用 2025-09-03（最新版本）。在此版本中，數據庫在 API 中被稱為“數據源”。

常見操作

搜索

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"

獲取頁面內容（塊）

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

在數據庫中創建頁面

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

屬性類型

數據庫條目的常見屬性格式：

• 標題： {"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": "user@example.com"}
• 關聯： {"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

注意事項

• 頁面/數據庫 ID 為 UUID（帶或不帶連字符均可）
• 速率限制：平均約 3 次請求/秒
• API 無法設置數據庫視圖過濾器——這僅限 UI 操作
• 創建數據源時使用 is_inline: true 將其嵌入頁面
• 向 curl 添加 -s 標誌以抑制進度條（為 Hermes 提供更清晰的輸出）
• 通過 jq 管道輸出以獲得可讀的 JSON：... | jq '.results[0].properties'