Notion

简介

Notion API 让你以编程方式读写 Notion 页面、数据库和块——构建自动化、同步内容，并在 Notion 工作区之上创建工具。认证是 OAuth（集成令牌）——没有匿名访问。

快速开始

需要集成令牌（来自 Notion 集成的 secret_...）：

# 列出集成可访问的页面/数据库：
curl "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28"

查询数据库：

curl -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'

创建页面：

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer YOUR_INTEGRATION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"database_id": "DATABASE_ID"}, "properties": {"Name": {"title": [{"text": {"content": "New task"}}]}}}'

认证方式

• 在 notion.so/my-integrations 创建集成 → 复制内部集成令牌（secret_...）。
• 通过 Authorization: Bearer ... 发送，并带 Notion-Version 头（始终需要，如 2022-06-28）。
• OAuth（公开集成）是同一套 API，用用户授权的令牌——列表的 OAuth 标记即指此。

速率限制与注意事项

• 速率限制：每个集成约 3 次请求/秒——请缓存响应。
• 始终发送 Notion-Version 头——API 是版本化的。
• 集成只能看到已共享给它的页面/数据库（需在 UI 里把页面共享给集成）。
• 数据库查询是 POST 到 /v1/databases/{id}/query（JSON body），不是 GET。

常见问题

Notion API 免费吗？ 是的——集成使用 API 免费（在速率限制内）。

需要 OAuth 吗？ 内部集成用令牌；公开集成用 OAuth——同一套 API。

为什么集成看不到页面？ 你必须在 Notion UI 中把每个页面/数据库共享给集成。