Notion · 2026.06.09 · 8 min read
Notion API 用 curl 測試教學：5 個最常用 endpoint 速查（2026）
Notion API 用 curl 測試教學：5 個最常用 endpoint 速查（2026）
解答先行
Notion API 新手最容易犯的錯，是一開始就去寫完整程式。
我會反過來建議：先用 curl 把 5 個 endpoint 跑通，再決定要不要寫 JavaScript、Python、n8n 或 Cloudflare Workers。
這 5 個 endpoint 的順序是：
| 順序 | endpoint | 用途 | 主要排查什麼 |
|---|---|---|---|
| 1 | GET /v1/users/me |
確認 token 可用 | 401 |
| 2 | POST /v1/search |
找 page / data source | 403、授權範圍 |
| 3 | GET /v1/pages/{page_id} |
讀取頁面 metadata | page id 是否正確 |
| 4 | POST /v1/data_sources/{data_source_id}/query |
查資料列 | filter、sort、pagination |
| 5 | POST /v1/pages |
建立新頁面 | Insert Content 權限、欄位型別 |
如果你還沒有拿到 token，先回去看母文：Notion API Key 怎麼拿？Integration Token 申請、資料庫授權與 curl 測試 4 步搞定。
這篇只處理一件事：用最小指令確認 Notion API 真的能讀、能查、能寫。
開始前先準備 3 個東西
你需要：
| 變數 | 代表什麼 | 怎麼取得 |
|---|---|---|
NOTION_API_KEY |
Notion integration token / API token | Notion Developer Portal |
PAGE_ID |
某個已授權 page 的 ID | 用 search 找，或從網址拆 |
DATA_SOURCE_ID |
database 底下實際可 query 的 data source ID | 用 search 或 database 回傳資訊確認 |
2026 年寫 Notion API，要先注意一件事：Notion 官方在 2025-09-03 之後把 database 和 data source 分開。
白話講：
| 名詞 | 你可以怎麼理解 |
|---|---|
| database | Notion UI 裡看到的資料庫容器 |
| data source | 真正放資料列、可 query 的表 |
| page | data source 裡的一筆資料，或一般頁面 |
所以現在查資料列時，主路徑會是：
POST /v1/data_sources/{data_source_id}/query
不是一律照舊教學寫：
POST /v1/databases/{database_id}/query
舊 endpoint 在部分情境仍可能看得到，但新文章建議直接用 data source 的語言，後面接 webhook、views、multi-source database 才不會一直重改。
先把 token 放到環境變數
不要把 token 直接貼在指令裡。
終端機先設定：
export NOTION_API_KEY="ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
之後每個 curl 都用：
-H 'Authorization: Bearer '"$NOTION_API_KEY"''
這樣你比較不會把 token 截圖、貼文或 commit 到 repo。
所有指令都會用同一個 API version：
-H "Notion-Version: 2026-03-11"
截至 2026-06-09，Notion 官方文件列出的最新版本是 2026-03-11。這版已經把一些舊欄位移除，例如 archived 改成 in_trash。
Endpoint 1：測 token 是否有效
第一個不要查 database。
先打：
curl -X GET "https://api.notion.com/v1/users/me" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
如果成功，你會看到 bot / user 相關資訊。
這一步只回答一個問題：
這組 token 有沒有被 Notion 接受？
| 結果 | 代表什麼 | 下一步 |
|---|---|---|
| 200 | token 有效 | 繼續測 search |
| 401 | token 錯、漏 Bearer、複製不完整 | 回 Developer Portal 重複製 |
| 403 | 較少出現在這一步 | 檢查 integration 狀態與 workspace 權限 |
如果這一步都不過，後面不用測。
先把 token 修好。
Endpoint 2：用 search 找 page 和 data source
第二個 endpoint 是 POST /v1/search。
它的用途不是精準查某張表，而是先看這個 connection 目前看得到什麼。
curl -X POST "https://api.notion.com/v1/search" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"page_size": 10
}'
如果你想只找 data source：
curl -X POST "https://api.notion.com/v1/search" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"query": "文章",
"filter": {
"value": "data_source",
"property": "object"
},
"page_size": 10
}'
這一步很重要，因為很多人以為：
我拿到 token，Notion API 就應該能讀所有頁面。
不是。
Notion API 只能讀 connection 被授權看到的資料。
如果 search 完全找不到你要的頁面，通常是這兩種原因：
| 問題 | 怎麼修 |
|---|---|
| 目標 page / database 沒有 Add connections | 到 Notion 右上角 ... 或 sharing / connections，把 integration 加進去 |
| 你在錯的 workspace 建 token | 回 Developer Portal 確認 connection 所在 workspace |
我自己排 Notion API 錯誤時，search 是最常用的第一道門。
它可以幫你判斷：問題是「token 壞了」，還是「token 好的，但看不到資料」。
Endpoint 3：讀取單一 page
找到 page id 後，可以讀單一頁面：
export PAGE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -X GET "https://api.notion.com/v1/pages/$PAGE_ID" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11"
這個 endpoint 主要拿來看 page 的 metadata 和 properties。
注意，它不是拿來直接抓完整文章內容。
| 你想拿什麼 | endpoint |
|---|---|
| page 標題、properties、parent | GET /v1/pages/{page_id} |
| block 內容 | GET /v1/blocks/{block_id}/children |
| markdown 內容 | GET /v1/pages/{page_id}/markdown |
如果你只是做內容同步、文章草稿、自媒體排程，通常會先用 pages.retrieve 看欄位，再決定要不要抓 blocks 或 markdown。
這一步常見錯誤：
| 狀態 | 常見原因 |
|---|---|
| 404 | page id 錯，或 connection 看不到這頁 |
| 403 | page 所在的上層沒有授權 |
| 200 但資料不完整 | 你拿到的是 page metadata，不是完整 blocks |
Endpoint 4：查 data source 裡的資料列
接著測 data source query。
先設定：
export DATA_SOURCE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
查前 10 筆：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"page_size": 10
}'
加上 filter：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"filter": {
"property": "Status",
"status": {
"equals": "Ready"
}
},
"page_size": 10
}'
加上 sort：
curl -X POST "https://api.notion.com/v1/data_sources/$DATA_SOURCE_ID/query" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"sorts": [
{
"property": "Last edited time",
"direction": "descending"
}
],
"page_size": 10
}'
這裡最容易卡在欄位名稱。
Notion API 的 filter property 要對上 data source 裡的 property 名稱。中文、空格、大小寫都可能讓你多花半小時。
如果你不確定欄位名稱，先 retrieve data source 或用 search / query 回傳結果看 schema，不要用猜的。
Endpoint 5：新增一筆 page 到 data source
最後才測寫入。
因為寫入需要比較高的權限。
你的 integration 必須有 Insert Content capability，目標 data source 也要授權給 connection。
curl -X POST "https://api.notion.com/v1/pages" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"parent": {
"type": "data_source_id",
"data_source_id": "'"$DATA_SOURCE_ID"'"
},
"properties": {
"Name": {
"title": [
{
"text": {
"content": "API 測試資料"
}
}
]
},
"Status": {
"status": {
"name": "Ready"
}
}
}
}'
這段有兩個地方要改：
| 欄位 | 要改成你的實際資料 |
|---|---|
Name |
你的標題欄位名稱，有些資料庫叫 Title、任務、Page |
Status |
你的狀態欄位名稱與選項 |
如果你的 data source 沒有 Status 欄位，就先拿掉。
最小寫入可以只保留 title property。
curl -X POST "https://api.notion.com/v1/pages" \
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
-H "Notion-Version: 2026-03-11" \
-H "Content-Type: application/json" \
--data '{
"parent": {
"type": "data_source_id",
"data_source_id": "'"$DATA_SOURCE_ID"'"
},
"properties": {
"Name": {
"title": [
{
"text": {
"content": "API 最小測試"
}
}
]
}
}
}'
如果這一步成功，你就已經完成 Notion API 的基本讀寫測試。
接下來才值得把 curl 改成 JavaScript、Python、n8n 或排程腳本。
401、403、404、429 怎麼判斷？
Notion API 排錯不要亂猜。
先看 status code。
| 狀態碼 | 最常見原因 | 你該做什麼 |
|---|---|---|
| 400 | JSON 格式錯、欄位型別不合、filter 寫錯 | 用 JSON formatter 檢查，先刪到最小 body |
| 401 | token 錯、漏 Bearer、token 被撤銷 | 重複製 token，確認 header |
| 403 | 權限不夠、沒 Add connections、缺 Insert Content capability | 回 Notion 授權與 integration capabilities |
| 404 | ID 錯，或 connection 看不到該資料 | 用 search 重新找 ID |
| 429 | 請求太頻繁 | 降低頻率，加 retry / backoff |
排錯順序我會這樣跑：
① GET /v1/users/me
② POST /v1/search
③ GET /v1/pages/{page_id}
④ POST /v1/data_sources/{id}/query
⑤ POST /v1/pages
不要從第 ⑤ 步開始。
因為你會分不清楚到底是 token、授權、ID、欄位，還是寫入能力出問題。
這 5 個 curl 跑通後，下一步怎麼選？
看你的目的。
| 你要做什麼 | 下一步 |
|---|---|
| 表單寫入 Notion | 先用 n8n / Zapier 接表單，再看是否要自己寫 API |
| Notion 同步 WordPress | 讀 data source → 抓 page markdown → 圖片轉 R2 → 更新文章 |
| 社群貼文工作流 | Notion API 讀排程資料，再交給 Metricool / Meta API |
| CRM 自動化 | 用 filter 查待處理客戶，再更新狀態 |
| 大量同步 | 不要無腦全表 query，改用時間欄位 filter 或 webhook |
如果你是新手，我不建議一開始就把 Notion API、n8n、AI、WordPress、社群發布全串在一起。
先做一條小流程：
Notion 寫一筆資料 → API 查得到 → API 能新增測試頁 → 再接下一個工具。
這樣你每次只排一個錯。
系統才會真的跑得起來。
FAQ
Notion API 新手一定要先學 curl 嗎？
不一定，但我建議先學。curl 可以讓你排除 SDK、n8n、Zapier、Python 套件帶來的干擾。只要 curl 成功，後面工具只是把同一件事包起來。
Notion API 查 database 要用 database id 還是 data source id？
2026 年的新寫法建議用 data_source_id 查資料列。database 比較像容器，data source 才是實際存資料的表。舊教學常用 /v1/databases/{id}/query，但新文章建議改成 /v1/data_sources/{id}/query。
為什麼 search 找不到我的資料庫？
通常是 connection 沒有被加到那個 page 或 database。到 Notion 右上角的 sharing / connections，把 integration 加進去，再重新打 search。
可以把 token 放在前端 JavaScript 嗎？
不建議。Notion API token 應該放在後端、serverless function、n8n credential、CI secrets 或本機環境變數。放前端等於把鑰匙交出去。
curl 成功後，要不要改用 SDK？
可以。SDK 適合正式專案，尤其是要處理分頁、錯誤、重試和型別時。但新手先用 curl 搞懂 HTTP 請求，之後看 SDK 文件會快很多。
資料來源
資料最後查核日期：2026-06-09
