SKILL.md
readonlyread-only
name
notion
description
Notion CLI/API，用於頁面、Markdown 內容、資料來源、檔案、留言、搜尋、Workers 及原始 API 呼叫。
Notion
優先使用官方 ntn CLI。只有在 ntn 不可用或原始請求更清楚時才使用 curl。
設定
npm install -g ntn
ntn --version
ntn login
腳本/無頭模式驗證：
export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11
ntn api 會自動設定 Authorization 和 Notion-Version。預設使用 CLI 登入，若設定了 NOTION_API_TOKEN 則使用該 token。
檢查
ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST
頁面
Markdown 優先的輔助工具：
ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Title\n\nBody'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# Updated'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes
注意事項：
pages get會輸出 Markdown，並將頁面屬性作為 frontmatter。- 內容輸入：
--content、標準輸入，或在 TTY 中開啟編輯器。 - 父參照：
page:<id>、database:<id>、data-source:<id>。 - 如需屬性/範本/完整 Pages API，請使用
ntn api v1/pages。
資料來源
ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort 'Date desc'
ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'
當你有資料庫 ID 時使用 resolve。查詢需要資料來源 ID。
原始 API
ntn api v1/users/me
ntn api v1/search query=roadmap page_size:=10
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item'
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
'children[0][type]=paragraph' \
'children[0][paragraph][rich_text][0][text][content]=Hello'
輸入語法：
path=value：字串 body 欄位。path:=json：型別化的 JSON body 欄位。name==value：查詢參數。Header:Value：請求標頭。--data '<json>'或標準輸入 JSON 用於較大的 body。- 每個請求只能有一個 body 來源。
檔案
ntn files create < image.png
ntn files create --filename photo.png --content-type image/png < /tmp/photo
ntn files create --external-url https://example.com/photo.png
ntn files get <upload-id>
ntn files list
Workers
ntn workers new
ntn workers deploy
ntn workers list --json
ntn workers runs list --json
ntn workers runs logs <run-id>
Workers 可能需要 Business/Enterprise 方案及工作區啟用。
Curl 備用方案
curl -sS "https://api.notion.com/v1/users/me" \
-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json"
版本說明
- 目前最新 API 版本：
2026-03-11。 - 使用
in_trash，而非archived。 - 區塊附加定位使用
position，而非平面的after。 transcription區塊已重新命名為meeting_notes。- 資料庫可包含多個資料來源；頁面父層通常使用
data_source_id。
