Notion 数据 API

适用主体

个人知识库工具开发者、团队自动化开发者、Notion 集成产品开发者

接入方式

用户级个人访问 Token（PAT） / 单工作区内部连接 API Token / 公开连接 OAuth 2.0 / 连接 Webhook 事件通知

申请概况

个人可用 PAT；团队连接和公开应用按工作区角色、资源权限与授权方式接入。

• 先选择个人脚本、团队自动化或多用户产品：PAT 代表创建者，内部连接作为独立 bot，公开产品使用 OAuth。
• 创建内部连接需要工作区所有者身份；PAT 仅供完整工作区成员创建，并受套餐默认策略与管理员设置约束。
• 创建凭证后仍需授予内容及操作权限；内部连接要明确共享页面或数据库，公开连接由用户在 OAuth 中选择可共享内容。
• REST 请求使用 Bearer Token，并指定 Notion-Version；上线前按当前版本核对数据库、数据源和分页行为。

1. 01

   确定连接类型

   个人工具选 PAT；团队共有自动化选内部连接；需要其他用户安装时选公开 OAuth 连接。

2. 02

   在 Notion 中配置凭证

   按官方入门和开发者模式说明进入 Developer portal，创建凭证并选择必要能力。

3. 03

   授予测试内容权限

   准备自己的测试页面与数据库，再按所选连接类型授权；不要把能创建 Token 等同于已能读写全部工作区。

4. 04

   验证内容与事件流程

   先做少量读取和创建，确认分页、错误处理及实际内容；使用 Webhook 时再验证回调和重复事件处理。

使用范围与限制

• PAT 不能代表整个组织，创建者失去页面或工作区权限时，PAT 也失去相应访问；PAT 不支持列出全部工作区用户。
• 内部连接、公开 OAuth 和 PAT 的内容授权机制不同，不应把共享给 bot 的步骤照搬到 PAT。
• 多人 Free 工作区的块上限可阻止部分连接继续创建内容；具体适用范围不同，不能概括为所有 API 写入均无限。
• 请求受连接、工作区和端点频控，以及负载大小和嵌套深度限制；出现 429 或 529 时处理 Retry-After。
• 写入返回 503 时可能已经保存，应先检查响应中的重试指引与资源现状，避免重复创建。
• 本条目不覆盖 Notion Agent、Workers 执行或 Enterprise Admin API 的独立资格和计费。

如何进行开发测试

• 正式 REST API：在选定工作区对实际页面和数据库生效。
• 开发验证：使用独立测试页面、数据库或工作区，并按官方 quickstart 创建测试用凭证。
• Webhook 测试：官方提供修改页面标题等测试步骤及签名验证示例，仍操作实际获授权内容；本次没有执行。
• 本次未确认与正式数据自动隔离的通用沙箱，不将测试凭证视为不会修改实际内容的保证。

以下资料用于核对本页内容。申请与使用时，请以对应接口的最新规则为准。

1. 01
   Notion 数据 API 与连接类型概览已核对官方资料 · 2026-10-15
2. 02
   REST 请求、版本与分页约定已核对官方资料 · 2026-10-15
3. 03
   内部连接与公开 OAuth 授权已核对官方资料 · 2026-10-15
4. 04
   PAT 创建资格、权限与工作区策略已核对官方资料 · 2026-10-15
5. 05
   内容、评论与用户信息权限已核对官方资料 · 2026-10-15
6. 06
   文件与媒体接入已核对官方资料 · 2026-10-15
7. 07
   连接 Webhook 设置、验证与测试已核对官方资料 · 2026-10-15
8. 08
   请求频控、大小限制与重试已核对官方资料 · 2026-10-15
9. 09
   Free 工作区块限制及适用连接已核对官方资料 · 2026-10-15
10. 10
    工作区套餐与开发者功能已核对官方资料 · 2026-10-15
11. 11
    使用 PAT 创建页面的官方入门已核对官方资料 · 2026-10-15
12. 12
    Notion 工作区内开发者模式与连接管理已核对官方资料 · 2026-10-15