notion-api

Notion API 技能

此技能可透過 Notion REST API 與 Notion 工作區互動。使用 curl 和 jq 進行直接 REST 呼叫，或根據任務需求撰寫臨時指令碼。

驗證

API 金鑰處理

1. 環境變數：檢查環境中是否有 NOTION_API_TOKEN
2. 使用者提供的金鑰：如果使用者在上下文中提供 API 金鑰，則使用該金鑰
3. 無可用金鑰：如果兩者皆無，使用 AskUserQuestion（或同等功能）向使用者請求 API 金鑰

重要：切勿在任何地方顯示、記錄或傳送 NOTION_API_TOKEN，除了在 Authorization 標頭中。確認其存在，若缺少則詢問，在請求中使用它——但絕不輸出或暴露它。

請求標頭

所有請求都需要這些標頭：

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

驗證驗證

透過擷取機器人使用者來測試 API 金鑰：

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

基礎 URL 與慣例

• 基礎 URL：https://api.notion.com
• API 版本：2025-09-03（必要標頭）
• 資料格式：所有請求/回應主體皆為 JSON
• ID：UUIDv4 格式（請求中可省略連字號）
• 時間戳記：ISO 8601 格式（2020-08-12T02:12:33.231Z）
• 屬性名稱：snake_case
• 空值：使用 null 而非空字串

速率限制

• 平均：每個整合每秒 3 個請求
• 突發：允許短暫超過此限制的突發
• 速率限制回應：HTTP 429，附帶 Retry-After 標頭
• 策略：收到 429 回應時實作指數退避

請求大小限制

類型	限制
每個承載的最大區塊元素數	1000
最大承載大小	500KB
富文字內容	2000 字元
URL	2000 字元
方程式	1000 字元
電子郵件地址	200 字元
電話號碼	200 字元
多選選項	100 個項目
關聯	100 個相關頁面
人員提及	100 個使用者
每次請求的區塊陣列	100 個元素

破壞性操作的確認

重要：在執行任何修改或刪除資料的操作之前，請先詢問使用者確認。這包括：

• 更新頁面或區塊
• 刪除/封存頁面或區塊
• 修改資料庫結構
• 建立頁面（如果是多個或批次）
• 任何大量操作

對於一組邏輯相關的操作，一次確認即可。

核心 API 端點

搜尋

搜尋所有可存取的頁面和資料庫：

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "搜尋詞",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

篩選值："page" 或 "data_source"（或省略以包含兩者）

頁面

擷取頁面

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

注意：這會回傳頁面屬性，而非內容。若要取得內容，請使用頁面 ID 呼叫「擷取區塊子項目」。

建立頁面

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "頁面標題"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "段落內容"}}]
        }
      }
    ]
  }' | jq

父層選項：

• {"page_id": "..."} - 在頁面下建立
• {"database_id": "..."} - 在資料庫中建立（舊版）
• {"data_source_id": "..."} - 在資料來源中建立（API v2025-09-03+）

更新頁面

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "更新後的標題"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

其他更新選項：cover、is_locked、in_trash

封存（刪除）頁面

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

擷取頁面屬性項目

對於超過 25 個引用的屬性：

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

區塊（頁面內容）

擷取區塊子項目

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

使用頁面 ID 作為 block_id 來取得頁面內容。檢查每個區塊的 has_children 以取得巢狀內容。

附加區塊子項目

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "新章節"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "這裡是內容"}}]
        }
      }
    ]
  }' | jq

每次請求最多 100 個區塊，最多 2 層巢狀。

請求主體中的位置選項：

• 預設：附加到結尾
• "position": {"type": "start"} - 插入到開頭
• "position": {"type": "after_block", "after_block": {"id": "block-id"}} - 在特定區塊之後插入

擷取區塊

curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

更新區塊

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "更新後的內容"}}]
    }
  }' | jq

更新會取代指定欄位的整個值。

刪除區塊

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

將區塊移至垃圾桶（可還原）。

資料庫

擷取資料庫

curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

回傳資料庫結構，包括資料來源和屬性。

查詢資料庫

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "狀態",
      "select": {"equals": "完成"}
    },
    "sorts": [
      {"property": "建立時間", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

請參閱 references/filters-and-sorts.md 以取得完整的篩選和排序文件。

建立資料庫

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "我的資料庫"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "名稱": {"title": {}},
        "狀態": {
          "select": {
            "options": [
              {"name": "待辦", "color": "red"},
              {"name": "進行中", "color": "yellow"},
              {"name": "完成", "color": "green"}
            ]
          }
        },
        "截止日期": {"date": {}}
      }
    }
  }' | jq

更新資料庫

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "更新後的標題"}}],
    "description": [{"text": {"content": "資料庫描述"}}]
  }' | jq

資料來源（API v2025-09-03+）

資料來源是資料庫中的個別表格。自 API 版本 2025-09-03 起，資料庫可包含多個資料來源。

建立資料來源

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "新資料來源"}}],
    "properties": {
      "名稱": {"title": {}},
      "描述": {"rich_text": {}}
    }
  }' | jq

使用者

列出所有使用者

curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

擷取使用者

curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

擷取機器人使用者（自身）

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

留言

擷取留言

curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

使用頁面 ID 作為 block_id 來取得頁面層級的留言。

建立留言

在頁面上：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "留言內容"}}]
  }' | jq

回覆討論串：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "回覆內容"}}]
  }' | jq

注意：API 無法開始新的內嵌討論串或編輯/刪除現有留言。

分頁

支援分頁的端點會回傳：

• has_more：布林值，表示是否有更多結果
• next_cursor：下一頁的游標
• results：項目陣列

若要迭代所有結果：

1. 發出初始請求（省略 start_cursor）
2. 檢查回應中的 has_more
3. 若為 true，取出 next_cursor 並在下一個請求中作為 start_cursor 包含
4. 重複直到 has_more 為 false

使用游標的請求範例：

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

錯誤處理

HTTP 狀態	代碼	描述
400	invalid_json	請求主體不是有效的 JSON
400	invalid_request_url	URL 格式錯誤
400	invalid_request	不支援的請求
400	validation_error	請求主體不符合預期結構
400	missing_version	缺少 Notion-Version 標頭
401	unauthorized	無效的 Bearer 權杖
403	restricted_resource	權杖缺少權限
404	object_not_found	資源不存在或未與整合共用
409	conflict_error	交易期間資料衝突
429	rate_limited	超過速率限制（檢查 Retry-After 標頭）
500	internal_server_error	非預期的伺服器錯誤
503	service_unavailable	Notion 無法使用或超過 60 秒逾時
503	database_connection_unavailable	資料庫無回應
504	gateway_timeout	請求逾時

最佳實務

1. 儲存 ID：建立頁面/資料庫時，儲存回傳的 ID 以供未來更新使用
2. 使用屬性 ID：以 ID 而非名稱來引用屬性，以確保穩定性
3. 批次操作：將多個小型操作合併為較少的請求
4. 尊重速率限制：對 429 回應實作指數退避
5. 檢查 has_more：對於清單端點，務必處理分頁
6. 更新前驗證：在進行更新前，先擷取目前狀態
7. 使用環境變數：切勿將 API 金鑰寫死在程式碼中
8. 優雅處理錯誤：檢查回應狀態碼和錯誤訊息
9. 結構大小：保持資料庫結構在 50KB 以下以獲得最佳效能
10. 屬性限制：超過 25 個頁面引用的屬性需要個別擷取

參考資料

如需特定主題的詳細文件，請參閱：

• references/block-types.md - 所有支援的區塊類型及其結構
• references/property-types.md - 資料庫屬性類型和值格式
• references/filters-and-sorts.md - 資料庫查詢篩選和排序語法
• references/rich-text.md - 富文字物件結構和註解