官方 JS SDK 类型齐全，类型推断到 property level
速率约 3 req/s 平均，批量同步容易触发
到 notion.so/my-integrations 创建一个 internal integration，复制 secret token。把要操作的 page / database 在 Notion 里"共享"给该 integration。之后用 Authorization: Bearer <token> 和 Notion-Version 头调用 API。
可用率 · 30 天窗口
关于这个 API
Notion API 让开发者把 Notion 当作可编程的工作空间——读写 page、查询和过滤 database、操作 block 树。对个人开发者最常见的用法是把 Notion 当 headless CMS：把博客文章、产品改动日志、知识库内容存进 database，前端站点通过 API 拉取并渲染。
它的认证有两套：internal integration 适合自用，生成一个 token 直接用，无需 OAuth 跳转；public integration 走标准 OAuth，方便发布到 Notion 的应用市场。无论哪种，integration 都需要被 page/database 显式"shared"才能访问，这是 Notion 的权限模型。
block 模型是 Notion 数据结构的核心：每个 page 是 block 容器，block 可以是段落、heading、列表、code、子 database 等。读 page 时通常要先取 page metadata，再分页拉 block 树。速率限制平均约 3 req/s，批量同步操作需要节奏控制。一些 property 类型（rollup、formula、关联回链）通过 API 是只读的，写入需走 UI 或上游字段。
你可以做什么
- 1把 Notion 当 headless CMS 给博客或站点供数据
- 2从外部系统同步数据到 Notion database
- 3搭建跨工具的自动化（如 Linear issue → Notion）
- 4用 Notion 内容生成报告或 PDF
- 5为团队构建只读看板或公开页
优劣对比
优点
- 官方 JS SDK 类型齐全，类型推断到 property level
- 内部 integration 模式即开即用，无需 OAuth 跳转
- block 模型表达力强，能存储富文本与嵌套结构
- 社区中间件（@notionhq/notion-to-md 等）成熟
注意事项
- 速率约 3 req/s 平均，批量同步容易触发
- 某些 property 类型只读（如 rollup、formula）
- 分页大小默认 100，跨页拼装较繁琐
示例请求
curl https://notion.com/<endpoint> \
-H "Authorization: Bearer $ACCESS_TOKEN"快速开始
到 notion.so/my-integrations 创建一个 internal integration，复制 secret token。把要操作的 page / database 在 Notion 里"共享"给该 integration。之后用 Authorization: Bearer <token> 和 Notion-Version 头调用 API。
常见问题
API 收费吗？+
API 本身免费，但目标 workspace 必须是付费 plan 才能解锁某些高级功能（如多人协作的精细权限）。
为什么提示 page not found？+
最常见原因：integration 没被显式 share 到该 page/database。Notion 的权限是按 integration 粒度授权。
能修改 formula 字段吗？+
不行，formula、rollup、created_by、last_edited_by 这类 derived/system property 通过 API 只读。
一次能取多少条 database 记录？+
默认 page_size 100，最大 100。需要更多用 next_cursor 分页。
技术细节
- 认证方式
- oauth
- 计费
- freemium
- 协议
- REST
- SDK
- javascript, typescript, python
- 响应时间
- 709 ms
- 上次巡检
- 2026/5/12 07:37:58
接口端点
从 OpenAPI spec 自动解析。显示 12 / 13 个未弃用端点。
/v1/blocks/{id}BlocksDelete a block
/v1/blocks/{id}BlocksRetrieve a block
/v1/blocks/{id}BlocksUpdate a block
/v1/blocks/{id}/childrenBlocksRetrieve block children
/v1/blocks/{id}/childrenBlocksAppend block children
/v1/commentsCommentsRetrieve comments
/v1/databases/{id}DatabasesRetrieve a database
/v1/databases/{id}DatabasesUpdate a database
/v1/databases/{id}/queryDatabasesQuery a database
/v1/pages/{id}PagesRetrieve a Page
/v1/pages/{id}PagesUpdate Page properties
/v1/pages/{page_id}/properties/{property_id}PagesRetrieve a Page Property Item
另有 1 个端点未显示，详见 OpenAPI spec。
可以替代的选择
不同公司、解决相似问题的备选。按分类、认证、计费档位与标签重合度匹配。