為什麼要用 Notion API？API Key、Token、授權資料庫與 curl 測試教學（2026）

很多人搜尋 notion api、notion api key、notion api token，其實不是想研究 API 本身。

真正想做的通常是這幾件事：

• Typeform 表單填完，自動寫進 Notion
• n8n 抓資料後，更新 Notion 任務狀態
• 本地 Markdown 草稿同步到 Notion
• Notion 文章同步到 WordPress
• AI 產文後，把結果寫回 Notion database
• 客戶、專案、內容排程可以自動更新

也就是說，你不是為了炫技才需要 Notion API。

你需要它，是因為 Notion 已經變成你的資料中心，但資料不可能永遠只靠手動複製貼上。

如果你現在只是想拿到 Notion API Key，最短路徑是：

1. 建立 Notion connection / integration
2. 取得 token
3. 把目標頁面或資料庫授權給這個 connection
4. 用 curl 測一次 API

先把這四步跑通，再去想 n8n、WordPress、自動化、SDK，成功率會高很多。

為什麼要用 Notion API？

Notion 最好用的地方，是 database。

你可以把文章、任務、客戶、專案、靈感、會議紀錄都放進資料庫，然後用不同 View 管理。但只要你開始經營網站、社群、自動化流程，就會遇到一個問題：

Notion 裡的資料很好整理，但外部工具不會自己知道。

例如：

• 你在 Notion 寫完文章，WordPress 不會自己更新
• 你在 Typeform 收到表單，Notion 不會自己新增一筆資料
• 你在 n8n 跑完流程，Notion 不會自己改狀態
• 你讓 AI 生成社群貼文，Notion 不會自己存版本

這時候 Notion API 的角色就出現了。

它讓外部工具可以用一套標準方式讀取、建立、更新 Notion 裡的資料。

你想做的事	不用 API 的做法	用 API 的做法
表單資料進 Notion	手動複製	表單送出後自動新增資料列
Notion 同步 WordPress	手動貼文章	腳本讀 Notion 後更新 WP
社群貼文排程	Notion 寫完再手動整理	AI 產文後回寫狀態與版本
每日報表	手動貼數字	排程把資料寫進 Notion
CRM 更新	人工改狀態	外部事件觸發更新欄位

所以我會把 Notion API 定位成：

讓 Notion 從「好用的工作區」變成「可以被其他工具讀寫的資料中心」。

如果你只是自己做筆記，不一定需要 API。
但如果你想把 Notion 接進網站、AI、自動化、CRM、內容系統，那 API 就是一定會碰到的路。

Notion API 是什麼？

API 可以先理解成「軟體之間溝通的標準語言」。

在 Notion API 裡，最常見的流程是：

1. 你用 token 證明自己有權限
2. 你告訴 Notion 想讀哪個頁面、資料庫或 data source
3. Notion 回傳 JSON
4. 你的程式再決定要新增、更新或同步到其他地方

Notion API 是 REST API。請求會送到：

https://api.notion.com

每次呼叫通常會需要三個重點 header：

Authorization: Bearer YOUR_TOKEN
Notion-Version: 2026-03-11
Content-Type: application/json

新手最常卡住的不是 API 太難，而是沒有搞懂這三層：

層級	你要理解什麼	常見錯誤
Token	你有沒有合法憑證	401 unauthorized
權限	目標資料有沒有授權給 connection	403 forbidden
資料結構	欄位名稱、型別、ID 是否正確	validation_error / object_not_found

只要你能分清楚是哪一層出錯，Notion API 其實沒有想像中難。

Notion API Key、Token、Integration Token、PAT 差在哪？

很多教學會混用這些詞：

• Notion API Key
• Notion API Token
• Notion Integration Token
• Notion Secret Key
• Notion Access Token
• Personal Access Token

新手可以先這樣理解：

你看到的詞	比較準確的理解	適合誰
API Key	搜尋用語，很多人用來指 token	新手搜尋時會看到
Integration Token	connection / integration 用來呼叫 API 的 token	內部自動化、單一 workspace
Access Token	OAuth 或授權流程拿到的 token	公開 app、讓別人安裝你的整合
Personal Access Token, PAT	以某個使用者身分呼叫 API 的 token	腳本、CLI、個人自動化
Secret Key	舊教學常見說法	通常也是在找 token

Notion 官方現在把整合分成幾種常見路線：

1. Internal connection：單一 workspace 內部用，適合自己的自動化。
2. Public connection：用 OAuth，適合做給別人安裝的公開工具。
3. Personal Access Token, PAT：用某個使用者的權限呼叫 API，適合腳本、CLI、CI。

如果你只是要做自己的 Notion 自動化，先從 internal connection 開始就好。

SDK 是什麼？一定要用 SDK 嗎？

SDK 可以理解成「官方幫你包好的工具包」。

你可以直接用 curl 或 fetch 呼叫 Notion API，也可以用 Notion 的 JavaScript SDK。SDK 的好處是，它幫你處理一些重複設定，讓程式碼比較乾淨。

例如你可以這樣初始化：

const { Client } = require("@notionhq/client");

const notion = new Client({
  auth: process.env.NOTION_ACCESS_TOKEN,
});

但新手不一定要一開始就用 SDK。

我會建議順序是：

1. 先用 curl 測 token 和權限
2. 確認 API 能通
3. 再改用 SDK 寫正式流程

原因很簡單：curl 比較接近底層。你可以清楚看到 header、endpoint、payload。當你連 curl 都打不通時，直接上 SDK 只會讓錯誤更難判斷。

Notion API 可以拿來做什麼？

Notion API 最適合拿來做「資料流」。

你可以把 Notion 當成資料來源，也可以把 Notion 當成資料目的地。

場景	Notion 扮演的角色	適合工具
表單收件	資料目的地	Typeform / Tally / n8n
內容排程	資料來源與狀態中心	Notion API / AI / Metricool
WordPress 同步	草稿來源	API + 腳本
CRM 客戶管理	客戶資料庫	n8n / Make / API
每日報表	報表寫入地	排程腳本 / API
AI 工作流	prompt、輸出、狀態紀錄	API + LLM

如果你只是偶爾整理資料，可能手動就好。

但如果你每週都在做同一件事，例如「文章寫完、複製到 WordPress、再回 Notion 改狀態」，那就很適合用 API。

延伸可以看：

• Notion 社群貼文工作流
• Notion 自動化完整教學
• Notion 整合 Metricool 教學

如何取得 Notion API Key / Token？

下面用新手最常用的 internal connection 來說。

步驟 1：進入 Notion Developer / Integrations

到 Notion 的 Developer portal 或 workspace 的 integration 設定，建立一個新的 internal connection。

你可以幫它取一個好懂的名字，例如：

• WordPress Sync
• n8n Automation
• Content Pipeline
• Local Script

名字不要亂取，因為之後你在 Notion 裡授權頁面或 database 時，會需要認出它。

步驟 2：取得 token

建立完成後，你會看到這個 connection 對應的 token。

請把它存進安全位置，例如：

export NOTION_ACCESS_TOKEN="你的 token"

不要把 token 貼到：

• 前端程式碼
• 公開 GitHub repo
• 截圖
• 文章範例
• 可以被外部下載的設定檔

Token 就是密碼。拿到 token 的人，有機會讀寫你授權給它的 Notion 內容。

步驟 3：把資料庫或頁面授權給 connection

這是最多人漏掉的一步。

拿到 token 只代表你有鑰匙，不代表你可以開所有門。

你還要回到 Notion，把目標 page、database 或 data source 授權給這個 connection。

常見位置是頁面右上角的：

Connections / Add connections

如果這一步沒做，最常看到的錯誤就是：

403 forbidden

用 curl 測試 Notion API

第一次測試，我不建議直接打最複雜的 database query。

先測 token 是否有效。

測試 1：確認 token 能用

curl "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11"

如果這一步成功，代表：

• token 格式基本正確
• Authorization header 沒寫錯
• Notion-Version 有帶

如果這一步都回 401，先不要急著查 database。你現在還在 token 層。

測試 2：用 search 找資料

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{}'

如果 search 能回資料，代表 API 基本能讀到你授權範圍內的內容。

如果你知道關鍵字，也可以加 query：

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{"query":"content"}'

測試 3：讀取 data source

現在 Notion 文件裡，資料庫相關操作會越來越常看到 data source 的概念。

如果你要查詢某個 data source，可以用：

curl -X POST "https://api.notion.com/v1/data_sources/YOUR_DATA_SOURCE_ID/query" \
  -H "Authorization: Bearer $NOTION_ACCESS_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  --data '{}'

新手先不要硬背 ID。

我會建議先用 search 找到目標，再確認自己拿的是對的 data source id。很多舊教學會拿 page id 或 database id，照抄時很容易錯。

Notion API 最常見錯誤怎麼排查？

先看 status code，不要一開始就重寫程式。

錯誤	最常見原因	先做什麼
401 unauthorized	token 錯、漏 Bearer、header 格式錯	重貼 token，檢查 Authorization
403 forbidden	目標內容沒有授權給 connection	到 Notion 補 Add connections
404 object_not_found	ID 錯、資源不存在、拿錯物件	用 search 重新找
validation_error	欄位名或型別不符合	回 Notion 檢查 property
429 too_many_requests	呼叫太頻繁	加 retry / backoff

我自己的排查順序固定是：

1. 先測 GET /v1/users/me
2. 再測 POST /v1/search
3. 確認目標內容有 Add connections
4. 再測 data source query
5. 最後才處理 properties payload

這樣你不會把授權問題誤判成程式碼問題。

Notion API 和 n8n、Make、Zapier 怎麼選？

不一定要一開始就寫程式。

如果你只是想先驗證流程，可以先用 n8n、Make、Zapier、Typeform 這類工具。等你確定資料流真的有價值，再用 API 寫得更穩。

階段	建議做法	原因
驗證想法	Typeform / Tally / Make	快速確認資料能進 Notion
半自動流程	n8n + Notion node	可視化、好排錯
穩定生產線	Notion API + 腳本	可控、可測試、可記錄 log
對外產品	Public connection + OAuth	給其他 workspace 安裝

如果你是新手，我會建議：

先 no-code 跑通，再用 API 重做核心流程。

這比一開始就寫完整自動化更穩。

MCP、CLI、API 要怎麼選？

現在 Notion 生態裡不只 API。你還可能看到 MCP、CLI、PAT。

簡單分工：

工具	適合用途
Notion API	穩定、可排程、可重複的資料流
Notion SDK	用程式更舒服地呼叫 API
Notion CLI	開發者本機操作、測試、管理認證
PAT	腳本或 CI 以某個使用者權限執行
MCP	讓 AI 對話式讀取或操作 Notion

如果你要做「自動化生產線」，還是以 API 為主。

如果你只是想讓 AI 幫你查 Notion 筆記，MCP 會比較自然。

Notion API 速率限制與安全注意

Notion API 有 rate limit。官方常見建議是以平均每秒 3 個 request 當作保守上限來設計。

實務上你要做三件事：

1. 不要在迴圈裡無限制狂打 API
2. 遇到 429 要 retry，而不是直接失敗
3. 批次同步要做 checkpoint，避免中斷後全部重跑

安全上也很簡單：

• token 放環境變數
• CI/CD 用 secrets
• 不要放前端
• 不要 commit 到 GitHub
• 不同環境用不同 token
• 不用的 token 要 revoke

我會怎麼建議新手開始？

如果你今天是第一次碰 Notion API，我會照這個順序：

1. 建一個測試 database
2. 建一個 internal connection
3. 拿 token
4. 把測試 database Add connections 給它
5. 用 GET /v1/users/me 測 token
6. 用 POST /v1/search 測授權範圍
7. 用 data source query 讀資料
8. 再決定要接 n8n、WordPress、AI 或自己的腳本

不要一開始就把正式資料庫拿來測，也不要一開始就寫很大。

先讓第一個 request 成功。
Notion API 的學習曲線，大部分就卡在這一步。

延伸閱讀

• Notion Database 教學：資料庫完整入門
• Notion Workspace 教學：工作區建立與設定
• Notion 自動化完整教學
• Notion 社群貼文工作流
• Notion 備份完整教學

常見問題 FAQ

Notion API Key 要去哪裡拿？

到 Notion Developer portal 建立 internal connection / integration 後，就可以取得 token。取得後仍要把目標 page、database 或 data source 授權給這個 connection，否則常見 403。

Notion API Token 跟 Notion API Key 是同一個東西嗎？

多數搜尋情境下可以先當成同一件事理解。比較準確的說法是 token 或 integration token；API Key 通常只是大家搜尋時的叫法。

Notion Integration Token 和 PAT 差在哪？

Integration Token 通常用在某個 connection / integration；PAT 是 personal access token，會以某個使用者在 workspace 裡的權限呼叫 API。內部自動化先用 internal connection 就好。

為什麼我拿到 token 還是 403？

因為 token 只是憑證，不代表自動擁有所有資料權限。你要把目標頁面、database 或 data source 透過 Add connections 授權給這個 connection。

Notion API 新手第一個 curl 應該打哪個？

先打 GET /v1/users/me 測 token，再打 POST /v1/search 測授權範圍。不要一開始就打最複雜的 data source query。

Data Source ID 要怎麼找？

建議先用 POST /v1/search 找到目標內容，再確認你拿的是正確 data source。不要直接照抄舊教學裡從網址截出來的 ID。

SDK 是什麼？一定要用嗎？

SDK 是官方或工具方包好的開發工具包，像 Notion JavaScript SDK。它可以讓程式碼比較乾淨，但新手建議先用 curl 打通，再改用 SDK。

Notion API 免費嗎？

Notion API 本身不另外收費，但你能不能使用某些 Notion 功能，仍取決於你的 Notion 帳號方案、workspace 設定與權限。

Notion API 可以和 n8n 一起用嗎？

可以。新手可以先用 n8n 的 Notion node 跑通流程，等流程穩定後，再把核心部分改成 API 腳本。

Notion API Token 要怎麼保存才安全？

請放環境變數或 secrets manager，不要放在公開 repo、前端程式碼、文章截圖或可被外部下載的設定檔。

資料來源

資料最後查核日期：2026-05-17

• Notion Developers: Authentication：https://developers.notion.com/reference/authentication
• Notion Developers: Introduction：https://developers.notion.com/reference
• Notion Developers: Getting started overview：https://developers.notion.com/guides/get-started/overview
• Notion Developers: Personal access tokens：https://developers.notion.com/guides/get-started/personal-access-tokens
• Notion Developers: Working with databases：https://developers.notion.com/guides/data-apis/working-with-databases