Notion API 能做什麼？完整功能解析與 Python 整合指南

Notion API 免費開放完整 CRUD 能力，支援 30+ 種區塊類型。這篇文章整理了所有端點、限制與 Python 範例。

Notion 不只是筆記工具

很多人把 Notion 當筆記軟體用，但它其實有一套完整的 REST API，讓你用程式讀取、搜尋、編輯裡面所有的內容。更重要的是，這套 API 完全免費，不需要付費方案就能使用。

最近研究了一下 Notion API 的功能，整理成這篇指南。如果你想把 Notion 整合進自己的工作流，或是用程式自動化一些重複操作，這篇應該能幫上忙。

三個最常見的問題

在研究之前我最想知道的三件事：

1. 能不能用程式讀取 Notion 的筆記內容？ 可以。
2. 能不能用程式編輯 Notion？ 可以，而且是完整的 CRUD（建立、讀取、更新、刪除）。
3. 要怎麼開始？ 建一個 Integration、拿到 Token、裝個 Python SDK 就行。

接下來展開說明。

讀取能力：不只能讀，還能搜

頁面內容是透過「區塊」（Block）的概念來組織的。Notion API 支援超過 30 種區塊類型：

• 文字類：paragraph、heading_1/2/3、quote、callout、code
• 清單類：bulleted_list_item、numbered_list_item、to_do、toggle
• 媒體類：image、video、audio、file、pdf、embed、bookmark
• 版面類：divider、table、table_row、column_list、column
• 參照類：child_page、child_database、synced_block、table_of_contents
• 特殊類：equation（KaTeX 數學公式）、link_preview、mention

換句話說，你在 Notion 頁面上看到的所有東西，API 幾乎都能讀到。

編輯能力：完整的 CRUD

這代表你可以用程式做到：自動建立每日報告頁面、根據外部資料更新資料庫欄位、在頁面上自動追加會議紀錄，甚至用腳本管理整個專案看板。

速率限制與技術限制

API 是免費的，但有使用限制：

超過頻率限制會收到 HTTP 429 回應，帶有 Retry-After header 告訴你等多久。對個人自動化來說，每秒 3 次已經非常夠用。

認證方式：兩種選擇

大部分人只需要 Internal Integration。流程很簡單：

1. 到 notion.so/my-integrations 建立一個 Integration
2. 取得 API Token
3. 在 Notion 裡，對要操作的頁面或資料庫點「...」→「Connect to」→ 選擇你的 Integration

第三步很關鍵。Notion 的安全模型是「明確授權」，Integration 預設不能存取任何內容，你必須手動把每個要操作的頁面或資料庫連接上去。

每個 API 請求需要三個 HTTP Header：

Authorization: Bearer {your_token}
Content-Type: application/json
Notion-Version: 2022-06-28

Python 整合範例

Python 社群維護了一個官方 SDK notion-sdk-py，支援同步和非同步操作。

安裝：

pip install notion-client

基本讀取

import os
from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

# 搜尋工作區
results = notion.search(query="會議紀錄")

# 讀取頁面內容
blocks = notion.blocks.children.list(block_id="page_id_here")
for block in blocks["results"]:
    if block["type"] == "paragraph":
        texts = block["paragraph"]["rich_text"]
        content = "".join([t["plain_text"] for t in texts])
        print(content)

# 查詢資料庫（帶篩選）
response = notion.databases.query(
    database_id="db_id_here",
    filter={
        "property": "Status",
        "select": {"equals": "In Progress"}
    },
    sorts=[{"property": "Created", "direction": "descending"}]
)

建立頁面與寫入內容

new_page = notion.pages.create(
    parent={"database_id": "db_id_here"},
    properties={
        "Name": {
            "title": [{"text": {"content": "自動建立的頁面"}}]
        },
        "Status": {
            "select": {"name": "Not Started"}
        }
    },
    children=[
        {
            "object": "block",
            "type": "heading_2",
            "heading_2": {
                "rich_text": [{"text": {"content": "這是自動生成的標題"}}]
            }
        },
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {
                "rich_text": [{"text": {"content": "這段內容由 Python 腳本寫入。"}}]
            }
        }
    ]
)

在現有頁面追加內容

notion.blocks.children.append(
    block_id="page_id_here",
    children=[
        {
            "object": "block",
            "type": "to_do",
            "to_do": {
                "rich_text": [{"text": {"content": "自動新增的待辦事項"}}],
                "checked": False
            }
        }
    ]
)

如果不想裝 SDK，用 requests 也可以：

import requests, os

headers = {
    "Authorization": f"Bearer {os.environ['NOTION_TOKEN']}",
    "Content-Type": "application/json",
    "Notion-Version": "2022-06-28"
}

resp = requests.post(
    "https://api.notion.com/v1/search",
    headers=headers,
    json={"query": "研究筆記"}
)

常見的自動化場景

2025 年的重大更新：Data Sources

Notion 在 2025 年 9 月推出了新的 API 版本（2025-09-03），引入「Data Sources」的概念。簡單說，一個資料庫現在可以有多個資料來源，類似 Excel 的多個工作表。

這是一個破壞性變更。如果你的 Integration 使用舊版 API，而資料庫被新增了第二個資料來源，原有的整合會停止運作。建議新專案直接使用最新版 API。

小結

Notion API 的功能比我預期的完整：免費、支援完整 CRUD、30+ 種區塊類型、Python SDK 成熟。每秒 3 次的速率限制對個人自動化綽綽有餘。

如果你想開始用，三步就行：

1. 建立 Integration，取得 Token
2. 在 Notion 裡授權要操作的頁面
3. pip install notion-client，開始寫程式

官方文件寫得相當清楚，推薦從 Getting Started 開始。

如果這篇對你有幫助，歡迎分享給也在用 Notion 的朋友。