API Provider Dataset

# Notion — API Provider 档案

<!-- NOTICE:BEGIN v2026-10-01 -->
> 本档案的数据检索、分析与归纳由 AI agent 完成，不排除存在不完善或错漏之处。网络信息也会随时间变化，因此使用这些数据时请把这一不确定性计入。建议通过档案内提供的来源链接、并辅以额外的网络检索做进一步核实。若你发现本档案与事实存在差异，欢迎通过官网或购买后台的联系方式告知我们；我们也会定期对数据做复核与补充。
<!-- NOTICE:END -->

- **官网**:https://www.notion.com
- **文档**:https://developers.notion.com  
  ↳ 来源:https://developers.notion.com
- **slug**:`notion`

## B · 公司画像
- **定位**:Notion 是一体化 AI 工作空间（all-in-one AI workspace），把笔记、文档、知识库（wiki）、项目、任务与数据库整合到同一平台，并在其上提供 Notion AI、Custom Agents、AI Meeting Notes、Enterprise Search 等 AI 能力，让团队把日常工作与 agent 放在一起协作。官网自我定位为『团队与 agent 共同思考的地方』（Where teams and agents think together），强调 capture 知识、instant 找答案、automate 琐事；官网称其被 98% 的 Forbes Cloud 100 公司使用。公司总部位于旧金山，团队背景涵盖计算、历史、艺术、编程语言等。
- **API 整体作用**:Notion 的开发者平台以 REST API（base URL https://api.notion.com）为核心，让『connection』（集成）把工作空间与外部 SaaS、自动化脚本或自建工具打通，并用代码读写工作空间中的内容。API 支持读取/创建/更新几乎一切对象——pages、databases/data sources、users、comments、views、files、blocks，并可通过 webhook 订阅实时事件。围绕同一套鉴权还衍生出多条产品线：Agent APIs（与 Custom Agents 开会话）、Agent Skills API（下载存于 Notion 的 skill）、Notion MCP（让 MCP 客户端连接工作空间）、Workers（在 Notion 内跑自定义代码/agent tool/同步）、CLI，以及面向企业的 Admin API（合规、审计、legal hold、权限组、MCP/PAT 管理等）。
- **业务逻辑**:以订阅制 SaaS 为主：按成员（seat）收费的 Free / Plus / Business / Enterprise 套餐（月付或年付，年付最高省 20%），并按套餐解锁 AI、权限、安全与合规能力。AI 相关功能采用 credits 计费（Custom Agents 免费试用后 $10 / 1,000 monthly Notion credits；Workers 自 10 月 15 日起消耗 credits）。开发者生态通过公开 connection 与 Marketplace 扩展，API 本身不单独计价，而是随套餐提供。  
  ↳ 来源:https://www.notion.com/pricing
- **目标用户**:开发者、团队与企业。细分包括：想把外部工具接入 Notion 或做内部自动化的开发者（internal connection / PAT）；面向众多 Notion 用户与工作空间发布 SaaS 产品或服务的第三方（public connection，OAuth）；以及做企业级合规、审计与权限管理的组织（Admin API）。  
  ↳ 来源:https://developers.notion.com
- **行业**:data-analytics, productivity-software

## C · 能力形状
**API 面(按 baseURL 分组)**:
- `https://api.notion.com/v1`
  - **Notion Blocks API**
  - **Notion Comments API**
  - **Notion Databases API**
  - **Notion Pages API**
  - **Notion Search API**
  - **Notion Users API**

**能力标签**:Collaboration, Database, Ideas, Notes, Productivity, Project, T1, Task, Wiki, Workspace

> ⚠️ apis[] 6 条为按 tag 拆分的 spec 文件, 归入 1 个 base 面, 非独立产品清单(计数=spec 非产品)。

- **行动清单(web 核实)**:创建页面（POST /v1/pages，支持 Notion-flavored Markdown 或 children blocks）；检索/更新/移动/删除（trash）页面；按 markdown 读取/更新页面内容；查询 data source、创建/检索/更新 database 与 data source、列出 data source 模板；追加/检索/更新/删除 block children；创建/更新/删除/检索/列出 comment；按标题搜索（POST /v1/search）；列出/检索 user 及当前 token 的 bot user；创建/发送/完成/检索/列出 file upload；创建/检索/更新/删除/列出 view 及其 query；创建与查询 AI meeting note；管理 Custom Agent（query/retrieve/insights/status/credit limit/delete/batch）与 agent session（创建、查询、取消、事件）；下载 Agent Skills 的 plugin/skill；订阅 webhook 事件（page/database/data source/comment/file upload/view 的创建、更新、删除等）；Admin API（legal hold、permission group、user、workspace export、MCP 连接、PAT 管理、agent 治理与 credits 策略）。  
  ↳ 来源:https://developers.notion.com/llms.txt
- **可用场景**:1) 把外部系统数据同步进 Notion 数据库并保持更新（Workers Syncs）；2) 用 agent 自动创建/更新页面、生成 AI meeting notes、整理评论与任务；3) 用户在安装 public connection 后，自动为其工作空间创建数据库、页面与视图；4) 通过 webhook 实时响应页面/数据库/评论变化，驱动自动化工作流；5) 企业用 Admin API 做合规审计、legal hold 与权限管理。  
  ↳ 来源:https://developers.notion.com/llms.txt
- **不适合场景**:不适合需要极低延迟或不受限流约束的高频调用（每 connection 每分钟 600/180 请求，另有 workspace 级共享限流）；单次请求受大小限制（payload 最多 1000 个 block、500KB，rich text 文本/URL 上限 2000 字符等），不适合大文件或海量数据传输（大文件须走多部分上传）；不适合作为通用计算引擎，或用于非 Notion 场景的存储与计算。  
  ↳ 来源:https://developers.notion.com/reference/request-limits

## D · 自主闸门
- **onboarding 信号**:self-serve · **public**:False
- **必须人做的环节**:需要 Notion 账号与工作空间；创建 token 时若出现 workspace picker 需先选工作空间；在 Business 与 Enterprise 套餐上 PAT 创建默认被限制，需工作空间 owner 在 Settings → Connections 中开启；创建 connection 时需选择安装范围（Any workspace 或 Selected workspaces only，创建后不可更改），public connection 还需最终用户在 OAuth 流程中通过 page picker 授权可访问的页面。  
  ↳ 来源:https://developers.notion.com/guides/get-started/quick-start
- **程序化自助开通**:个人/开发者可自助开通：在 Developer portal 打开 Personal access tokens → New token → 填名称并勾选 Notion API capability → Create token，拿到 token 后即可用 Bearer 头直接调用 API，无需 OAuth 或合同；internal connection 同样可自助创建。前提是已拥有 Notion 账号/工作空间，且部分套餐（Business/Enterprise）需管理员先开启 PAT 创建权限。  
  ↳ 来源:https://developers.notion.com/guides/get-started/quick-start
- **程序化付费**:未提供程序化付费通道。Notion 目前仅接受主流信用卡与借记卡，套餐按成员计费、在账单周期结算，文档未提及 API 下单或无需人工输卡的自助支付方式。  
  ↳ 来源:https://www.notion.com/pricing
- **ToS 是否禁 agent**:*未采集*

## E · 经济形状
- **定价信号**:freemium
- **结算方式**:订阅制为主：按成员（seat）计费的 Free / Plus / Business / Enterprise 套餐，可选月付或年付（年付最高省 20%），成员增减按比例（prorated）结算；叠加按量计费的 Notion credits（AI 功能 / Custom Agents / Workers）；站点自定义域名等按域名单独收费。  
  ↳ 来源:https://www.notion.com/pricing
- **免费档**:有 Free 档：个人使用 pages & blocks 不限量，含基础 forms/sites、Notion Calendar、数据库（含 subtasks/dependencies/custom properties）等；2 人及以上成员共享的 Free 工作空间有 block 数量上限（达到后仍可读/编辑/整理已有内容，但不能新增 block）。Plus/Business/Enterprise 提供 Notion AI 等的试用与更高额度。API 本身无单独定价，随工作空间套餐提供。  
  ↳ 来源:https://www.notion.com/pricing
- **单位成本**:Custom Agents：免费试用后 $10 per 1,000 monthly Notion credits；套餐本身按成员（seat）计价（具体单价以 pricing 页为准）；Workers 自 10 月 15 日起消耗 Notion credits。  
  ↳ 来源:https://www.notion.com/pricing
- **rate limit**:每 connection 每 60 秒窗口：Business/Enterprise 600 请求/分钟（约 10/秒），其它套餐 180 请求/分钟（约 3/秒）；另有跨工作空间所有 connection 共享的 per-workspace 限流（随套餐扩展），因此单个 connection 未超限也可能被限。超限返回 HTTP 429 与 code "rate_limited"（附 Retry-After，per-connection 最多 60 秒，per-workspace 可能更长）；过载返回 529 "service_overload"。另有限制：payload 最多 1000 个 block、500KB。  
  ↳ 来源:https://developers.notion.com/reference/request-limits

## F · 集成成熟度 & 风险
- **交付模型**:open-core · **callable_host**:True
- **surface 信号**:Security, RateLimits, AgenticAccess, OpenAPI, Documentation, JSONSchema
- **鉴权**:以 Bearer token 鉴权，支持三种认证模型：Internal connection（单工作空间静态 API token）、Public connection（OAuth 2.0，用户授权时选择页面）、Personal access token（用户级静态 bearer token）。请求头为 Authorization: Bearer <token>，并需带 Notion-Version（如 2026-03-11）。  
  ↳ 来源:https://developers.notion.com
- **SDK**:官方 JavaScript SDK：@notionhq/client（github.com/makenotion/notion-sdk-js），文档示例同时给出 cURL、HTTP、JavaScript 版本；另有 Notion CLI 与 Workers SDK（@notionhq/workers），并可用任意支持 HTTP 的语言/库调用。  
  ↳ 来源:https://developers.notion.com/reference/intro
- **OpenAPI spec**:https://developers.notion.com/openapi.json  
  ↳ 来源:https://developers.notion.com/llms.txt
- **sandbox**:*未采集*
- **可逆性**:多数操作为对工作空间内容的读写，副作用相对可控：页面/块可 update，删除页面为 trash（移入回收站）；但创建 comment 会通知相关用户、订阅的 webhook 会触发外部系统、file upload 会占用存储，删除 Custom Agent、revoke token、delete view/comment 等操作具不可逆或外部可见后果，调用前需谨慎。  
  ↳ 来源:https://developers.notion.com/llms.txt

---
*溯源:核实于 2026-09-17*

<!-- NOTICE:BEGIN v2026-10-01 -->
## 声明
1. 本档案是基于公开信息的事实汇编。
2. 其中引用的片段，权利归原权利人所有。
3. 标注为「自称」的内容是该公司的自我陈述，不是经我们核实的结论。
4. 所涉商标归各自所有者所有。
<!-- NOTICE:END -->

{
  "_schema": "api_provider_report/v1",
  "_stage": "completed",
  "A_identity": {
    "slug": "notion",
    "name": "Notion",
    "official_website": "https://www.notion.com",
    "doc_url": {
      "value": "https://developers.notion.com",
      "source_url": "https://developers.notion.com",
      "not_found": false
    }
  },
  "B_positioning": {
    "company_positioning": "Notion 是一体化 AI 工作空间（all-in-one AI workspace），把笔记、文档、知识库（wiki）、项目、任务与数据库整合到同一平台，并在其上提供 Notion AI、Custom Agents、AI Meeting Notes、Enterprise Search 等 AI 能力，让团队把日常工作与 agent 放在一起协作。官网自我定位为『团队与 agent 共同思考的地方』（Where teams and agents think together），强调 capture 知识、instant 找答案、automate 琐事；官网称其被 98% 的 Forbes Cloud 100 公司使用。公司总部位于旧金山，团队背景涵盖计算、历史、艺术、编程语言等。",
    "api_overall_role": "Notion 的开发者平台以 REST API（base URL https://api.notion.com）为核心，让『connection』（集成）把工作空间与外部 SaaS、自动化脚本或自建工具打通，并用代码读写工作空间中的内容。API 支持读取/创建/更新几乎一切对象——pages、databases/data sources、users、comments、views、files、blocks，并可通过 webhook 订阅实时事件。围绕同一套鉴权还衍生出多条产品线：Agent APIs（与 Custom Agents 开会话）、Agent Skills API（下载存于 Notion 的 skill）、Notion MCP（让 MCP 客户端连接工作空间）、Workers（在 Notion 内跑自定义代码/agent tool/同步）、CLI，以及面向企业的 Admin API（合规、审计、legal hold、权限组、MCP/PAT 管理等）。",
    "business_logic": {
      "value": "以订阅制 SaaS 为主：按成员（seat）收费的 Free / Plus / Business / Enterprise 套餐（月付或年付，年付最高省 20%），并按套餐解锁 AI、权限、安全与合规能力。AI 相关功能采用 credits 计费（Custom Agents 免费试用后 $10 / 1,000 monthly Notion credits；Workers 自 10 月 15 日起消耗 credits）。开发者生态通过公开 connection 与 Marketplace 扩展，API 本身不单独计价，而是随套餐提供。",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "target_users": {
      "value": "开发者、团队与企业。细分包括：想把外部工具接入 Notion 或做内部自动化的开发者（internal connection / PAT）；面向众多 Notion 用户与工作空间发布 SaaS 产品或服务的第三方（public connection，OAuth）；以及做企业级合规、审计与权限管理的组织（Admin API）。",
      "source_url": "https://developers.notion.com",
      "not_found": false
    },
    "industries": [
      "data-analytics",
      "productivity-software"
    ]
  },
  "C_capabilities": {
    "api_surfaces": [
      {
        "base_url": "https://api.notion.com/v1",
        "capabilities": [
          {
            "name": "Notion Blocks API"
          },
          {
            "name": "Notion Comments API"
          },
          {
            "name": "Notion Databases API"
          },
          {
            "name": "Notion Pages API"
          },
          {
            "name": "Notion Search API"
          },
          {
            "name": "Notion Users API"
          }
        ]
      }
    ],
    "tag_hints": [
      "Collaboration",
      "Database",
      "Ideas",
      "Notes",
      "Productivity",
      "Project",
      "T1",
      "Task",
      "Wiki",
      "Workspace"
    ],
    "surface_caveat": "apis[] 6 条为按 tag 拆分的 spec 文件, 归入 1 个 base 面, 非独立产品清单(计数=spec 非产品)。",
    "action_list": {
      "value": "创建页面（POST /v1/pages，支持 Notion-flavored Markdown 或 children blocks）；检索/更新/移动/删除（trash）页面；按 markdown 读取/更新页面内容；查询 data source、创建/检索/更新 database 与 data source、列出 data source 模板；追加/检索/更新/删除 block children；创建/更新/删除/检索/列出 comment；按标题搜索（POST /v1/search）；列出/检索 user 及当前 token 的 bot user；创建/发送/完成/检索/列出 file upload；创建/检索/更新/删除/列出 view 及其 query；创建与查询 AI meeting note；管理 Custom Agent（query/retrieve/insights/status/credit limit/delete/batch）与 agent session（创建、查询、取消、事件）；下载 Agent Skills 的 plugin/skill；订阅 webhook 事件（page/database/data source/comment/file upload/view 的创建、更新、删除等）；Admin API（legal hold、permission group、user、workspace export、MCP 连接、PAT 管理、agent 治理与 credits 策略）。",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "fit_scenarios": {
      "value": "1) 把外部系统数据同步进 Notion 数据库并保持更新（Workers Syncs）；2) 用 agent 自动创建/更新页面、生成 AI meeting notes、整理评论与任务；3) 用户在安装 public connection 后，自动为其工作空间创建数据库、页面与视图；4) 通过 webhook 实时响应页面/数据库/评论变化，驱动自动化工作流；5) 企业用 Admin API 做合规审计、legal hold 与权限管理。",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "unfit_scenarios": {
      "value": "不适合需要极低延迟或不受限流约束的高频调用（每 connection 每分钟 600/180 请求，另有 workspace 级共享限流）；单次请求受大小限制（payload 最多 1000 个 block、500KB，rich text 文本/URL 上限 2000 字符等），不适合大文件或海量数据传输（大文件须走多部分上传）；不适合作为通用计算引擎，或用于非 Notion 场景的存储与计算。",
      "source_url": "https://developers.notion.com/reference/request-limits",
      "not_found": false
    }
  },
  "D_autonomy_gate": {
    "onboarding_signal": "self-serve",
    "public": false,
    "human_steps": {
      "value": "需要 Notion 账号与工作空间；创建 token 时若出现 workspace picker 需先选工作空间；在 Business 与 Enterprise 套餐上 PAT 创建默认被限制，需工作空间 owner 在 Settings → Connections 中开启；创建 connection 时需选择安装范围（Any workspace 或 Selected workspaces only，创建后不可更改），public connection 还需最终用户在 OAuth 流程中通过 page picker 授权可访问的页面。",
      "source_url": "https://developers.notion.com/guides/get-started/quick-start",
      "not_found": false
    },
    "self_serve_activation": {
      "value": "个人/开发者可自助开通：在 Developer portal 打开 Personal access tokens → New token → 填名称并勾选 Notion API capability → Create token，拿到 token 后即可用 Bearer 头直接调用 API，无需 OAuth 或合同；internal connection 同样可自助创建。前提是已拥有 Notion 账号/工作空间，且部分套餐（Business/Enterprise）需管理员先开启 PAT 创建权限。",
      "source_url": "https://developers.notion.com/guides/get-started/quick-start",
      "not_found": false
    },
    "programmatic_payment": {
      "value": "未提供程序化付费通道。Notion 目前仅接受主流信用卡与借记卡，套餐按成员计费、在账单周期结算，文档未提及 API 下单或无需人工输卡的自助支付方式。",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "tos_agent_allowed": {
      "value": null,
      "source_url": null,
      "not_found": true
    }
  },
  "E_economics": {
    "pricing_model_signal": "freemium",
    "settlement_shape": {
      "value": "订阅制为主：按成员（seat）计费的 Free / Plus / Business / Enterprise 套餐，可选月付或年付（年付最高省 20%），成员增减按比例（prorated）结算；叠加按量计费的 Notion credits（AI 功能 / Custom Agents / Workers）；站点自定义域名等按域名单独收费。",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "free_tier": {
      "value": "有 Free 档：个人使用 pages & blocks 不限量，含基础 forms/sites、Notion Calendar、数据库（含 subtasks/dependencies/custom properties）等；2 人及以上成员共享的 Free 工作空间有 block 数量上限（达到后仍可读/编辑/整理已有内容，但不能新增 block）。Plus/Business/Enterprise 提供 Notion AI 等的试用与更高额度。API 本身无单独定价，随工作空间套餐提供。",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "unit_cost": {
      "value": "Custom Agents：免费试用后 $10 per 1,000 monthly Notion credits；套餐本身按成员（seat）计价（具体单价以 pricing 页为准）；Workers 自 10 月 15 日起消耗 Notion credits。",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "rate_limit": {
      "value": "每 connection 每 60 秒窗口：Business/Enterprise 600 请求/分钟（约 10/秒），其它套餐 180 请求/分钟（约 3/秒）；另有跨工作空间所有 connection 共享的 per-workspace 限流（随套餐扩展），因此单个 connection 未超限也可能被限。超限返回 HTTP 429 与 code \"rate_limited\"（附 Retry-After，per-connection 最多 60 秒，per-workspace 可能更长）；过载返回 529 \"service_overload\"。另有限制：payload 最多 1000 个 block、500KB。",
      "source_url": "https://developers.notion.com/reference/request-limits",
      "not_found": false
    }
  },
  "F_integration": {
    "delivery_model": "open-core",
    "callable_host": true,
    "surface_signals": [
      "Security",
      "RateLimits",
      "AgenticAccess",
      "OpenAPI",
      "Documentation",
      "JSONSchema"
    ],
    "auth_shape": {
      "value": "以 Bearer token 鉴权，支持三种认证模型：Internal connection（单工作空间静态 API token）、Public connection（OAuth 2.0，用户授权时选择页面）、Personal access token（用户级静态 bearer token）。请求头为 Authorization: Bearer <token>，并需带 Notion-Version（如 2026-03-11）。",
      "source_url": "https://developers.notion.com",
      "not_found": false
    },
    "sdk": {
      "value": "官方 JavaScript SDK：@notionhq/client（github.com/makenotion/notion-sdk-js），文档示例同时给出 cURL、HTTP、JavaScript 版本；另有 Notion CLI 与 Workers SDK（@notionhq/workers），并可用任意支持 HTTP 的语言/库调用。",
      "source_url": "https://developers.notion.com/reference/intro",
      "not_found": false
    },
    "openapi_spec_url": {
      "value": "https://developers.notion.com/openapi.json",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "sandbox": {
      "value": null,
      "source_url": null,
      "not_found": true
    },
    "reversibility": {
      "value": "多数操作为对工作空间内容的读写，副作用相对可控：页面/块可 update，删除页面为 trash（移入回收站）；但创建 comment 会通知相关用户、订阅的 webhook 会触发外部系统、file upload 会占用存储，删除 Custom Agent、revoke token、delete view/comment 等操作具不可逆或外部可见后果，调用前需谨慎。",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    }
  },
  "_provenance": {
    "verified_at": "2026-09-17"
  },
  "_notice": {
    "version": "2026-10-01",
    "lang": "zh",
    "data_disclaimer": "本档案的数据检索、分析与归纳由 AI agent 完成，不排除存在不完善或错漏之处。网络信息也会随时间变化，因此使用这些数据时请把这一不确定性计入。建议通过档案内提供的来源链接、并辅以额外的网络检索做进一步核实。若你发现本档案与事实存在差异，欢迎通过官网或购买后台的联系方式告知我们；我们也会定期对数据做复核与补充。",
    "legal": [
      "本档案是基于公开信息的事实汇编。",
      "其中引用的片段，权利归原权利人所有。",
      "标注为「自称」的内容是该公司的自我陈述，不是经我们核实的结论。",
      "所涉商标归各自所有者所有。"
    ]
  }
}

# Notion — API Provider Dossier

<!-- NOTICE:BEGIN v2026-10-01 -->
> The data in this dossier was retrieved, analyzed and summarized by AI agents, so gaps and errors cannot be ruled out. Information published on the web also changes over time, so please factor that uncertainty in when you use this data. We recommend verifying anything that matters against the source links provided in the dossier, supplemented by your own web research. If you find a discrepancy between this dossier and the facts, please tell us through the contact details on our website or in your purchase account; we also review and extend the data periodically.
<!-- NOTICE:END -->

- **Website**:https://www.notion.com
- **Docs**:https://developers.notion.com  
  ↳ source:https://developers.notion.com
- **slug**:`notion`

## B · Company Profile
- **Positioning**:Notion is an all-in-one AI workspace that brings notes, documents, wikis, projects, tasks, and databases together on one platform, and provides AI capabilities such as Notion AI, Custom Agents, AI Meeting Notes, and Enterprise Search, allowing teams to work alongside agents on their day-to-day work. The website describes it as “Where teams and agents think together,” emphasizing capturing knowledge, finding answers instantly, and automating busywork. The company says it is used by 98% of Forbes Cloud 100 companies. The company is headquartered in San Francisco, and its team has backgrounds in computing, history, art, programming languages, and other fields.
- **Overall role of the API**:Notion’s developer platform centers on a REST API (base URL https://api.notion.com), through which “connections” link workspaces with external SaaS products, automation scripts, or custom-built tools and enable programmatic reading and writing of workspace content. The API supports reading, creating, and updating nearly all object types—pages, databases/data sources, users, comments, views, files, and blocks—and subscribing to real-time events via webhooks. Several product lines build on the same authentication framework: Agent APIs (to start sessions with Custom Agents), Agent Skills API (to download skills stored in Notion), Notion MCP (to connect MCP clients to workspaces), Workers (to run custom code/agent tools/syncs within Notion), CLI, and the enterprise-focused Admin API (for compliance, audits, legal holds, permission groups, and MCP/PAT management, among other things).
- **Business logic**:Primarily subscription-based SaaS: Free / Plus / Business / Enterprise plans priced per member (seat), with monthly or annual billing (annual billing saves up to 20%), and AI, permissions, security, and compliance capabilities unlocked by plan. AI-related features use credits for billing (Custom Agents offer a free trial, then cost $10 / 1,000 monthly Notion credits; Workers consume credits starting October 15). The developer ecosystem is extended through public connections and the Marketplace; the API itself is not priced separately and is included with the plan.  
  ↳ source:https://www.notion.com/pricing
- **Target users**:Developers, teams, and enterprises. Segments include developers who want to connect external tools to Notion or build internal automation (internal connection / PAT); third parties publishing SaaS products or services to many Notion users and workspaces (public connection, OAuth); and organizations handling enterprise-grade compliance, audits, and permission management (Admin API).  
  ↳ source:https://developers.notion.com
- **Industries**:data-analytics, productivity-software

## C · Capability Shape
**API surfaces (grouped by baseURL)**:
- `https://api.notion.com/v1`
  - **Notion Blocks API**
  - **Notion Comments API**
  - **Notion Databases API**
  - **Notion Pages API**
  - **Notion Search API**
  - **Notion Users API**

**Capability tags**:Collaboration, Database, Ideas, Notes, Productivity, Project, T1, Task, Wiki, Workspace

> ⚠️ The 6 entries in apis[] are spec files split by tag and grouped under 1 base surface; they are not a list of independent products (count = specs, not products).

- **Action list (web-verified)**:Create pages (POST /v1/pages, supporting Notion-flavored Markdown or children blocks); retrieve/update/move/trash pages; read/update page content as Markdown; query data sources; create/retrieve/update databases and data sources; list data source templates; append/retrieve/update/delete block children; create/update/delete/retrieve/list comments; search by title (POST /v1/search); list/retrieve users and the bot user for the current token; create/send/complete/retrieve/list file uploads; create/retrieve/update/delete/list views and their queries; create and query AI meeting notes; manage Custom Agents (query/retrieve/insights/status/credit limit/delete/batch) and agent sessions (create, query, cancel, events); download Agent Skills plugins/skills; subscribe to webhook events (such as creation, update, and deletion of pages, databases/data sources, comments, file uploads, and views); Admin API (legal holds, permission groups, users, workspace exports, MCP connections, PAT management, agent governance, and credits policies).  
  ↳ source:https://developers.notion.com/llms.txt
- **Fit scenarios**:1) Sync data from external systems into Notion databases and keep it up to date (Workers Syncs); 2) use agents to automatically create/update pages, generate AI meeting notes, and organize comments and tasks; 3) after a user installs a public connection, automatically create databases, pages, and views in their workspace; 4) respond to page/database/comment changes in real time via webhooks to drive automated workflows; 5) use the Admin API for enterprise compliance audits, legal holds, and permission management.  
  ↳ source:https://developers.notion.com/llms.txt
- **Unfit scenarios**:Not suitable for high-frequency calls requiring extremely low latency or freedom from rate limits (600/180 requests per minute per connection, plus shared workspace-level rate limits); individual requests are subject to size limits (payloads of up to 1,000 blocks and 500 KB, rich-text strings/URLs of up to 2,000 characters, etc.), making it unsuitable for large files or bulk data transfer (large files must use multipart upload); not suitable as a general-purpose compute engine or for storage and computation outside Notion use cases.  
  ↳ source:https://developers.notion.com/reference/request-limits

## D · Autonomy Gate
- **Onboarding signal**:self-serve · **public**:False
- **Steps a human must do**:A Notion account and workspace are required; if a workspace picker appears when creating a token, a workspace must be selected first. On Business and Enterprise plans, PAT creation is restricted by default and must be enabled by a workspace owner under Settings → Connections. When creating a connection, an installation scope must be selected (Any workspace or Selected workspaces only; this cannot be changed after creation). Public connections also require end users to authorize accessible pages through a page picker in the OAuth flow.  
  ↳ source:https://developers.notion.com/guides/get-started/quick-start
- **Programmatic self-serve activation**:Individuals and developers can self-serve activation: in the Developer portal, open Personal access tokens → New token → enter a name and select the Notion API capability → Create token. Once the token is obtained, the API can be called directly with a Bearer header, with no OAuth or contract required. Internal connections can also be created on a self-serve basis. A Notion account/workspace is required, and some plans (Business/Enterprise) require an administrator to enable PAT creation first.  
  ↳ source:https://developers.notion.com/guides/get-started/quick-start
- **Programmatic payment**:No programmatic payment channel is provided. Notion currently accepts only major credit and debit cards. Plans are billed per member and settled on the billing cycle; the documentation does not mention API-based ordering or a self-serve payment method that does not require manually entering card details.  
  ↳ source:https://www.notion.com/pricing
- **ToS stance on agents**:*not collected*

## E · Economics
- **Pricing signal**:freemium
- **Settlement shape**:Primarily subscription-based: Free / Plus / Business / Enterprise plans billed per member (seat), with monthly or annual billing available (annual billing saves up to 20%) and prorated billing for changes in membership; supplemented by usage-based billing for Notion credits (AI features / Custom Agents / Workers); custom domains for sites and similar items are charged separately per domain.  
  ↳ source:https://www.notion.com/pricing
- **Free tier**:A free tier is available: individual use includes unlimited pages and blocks, as well as basic forms/sites, Notion Calendar, databases (including subtasks/dependencies/custom properties), and more. Free workspaces shared by two or more members have a block limit (after reaching it, existing content can still be read, edited, and organized, but no new blocks can be added). Plus/Business/Enterprise offer trials of Notion AI and other features, along with higher quotas. The API itself is not priced separately and is included with the workspace plan.  
  ↳ source:https://www.notion.com/pricing
- **Unit cost**:Custom Agents: free trial, then $10 per 1,000 monthly Notion credits; plans themselves are priced per member (seat), with specific rates listed on the pricing page; Workers consume Notion credits starting October 15.  
  ↳ source:https://www.notion.com/pricing
- **Rate limit**:Per 60-second window per connection: 600 requests per minute for Business/Enterprise (about 10/second), and 180 requests per minute for other plans (about 3/second). There is also a shared per-workspace rate limit across all connections in the workspace (which scales with the plan), so a single connection may be limited even if it has not exceeded its own limit. Exceeding the limit returns HTTP 429 with code "rate_limited" (with Retry-After; up to 60 seconds per connection, possibly longer per workspace); overload returns 529 "service_overload". Additional limits: payloads of up to 1,000 blocks and 500 KB.  
  ↳ source:https://developers.notion.com/reference/request-limits

## F · Integration Maturity & Risk
- **Delivery model**:open-core · **callable_host**:True
- **Surface signals**:Security, RateLimits, AgenticAccess, OpenAPI, Documentation, JSONSchema
- **Auth shape**:Authentication uses Bearer tokens and supports three authentication models: Internal connection (a static API token for a single workspace), Public connection (OAuth 2.0, with users selecting pages when granting access), and Personal access token (a user-level static bearer token). Requests must include the header Authorization: Bearer <token> and Notion-Version (e.g., 2026-03-11).  
  ↳ source:https://developers.notion.com
- **SDK**:Official JavaScript SDK: @notionhq/client (github.com/makenotion/notion-sdk-js). Documentation examples also provide cURL, HTTP, and JavaScript versions. There are also Notion CLI and Workers SDK (@notionhq/workers), and any language/library that supports HTTP can be used to make calls.  
  ↳ source:https://developers.notion.com/reference/intro
- **OpenAPI spec**:https://developers.notion.com/openapi.json  
  ↳ source:https://developers.notion.com/llms.txt
- **Sandbox**:*not collected*
- **Reversibility**:Most operations read or write workspace content and have relatively manageable side effects: pages/blocks can be updated, and deleting a page means trashing it (moving it to the trash). However, creating a comment notifies relevant users, subscribed webhooks trigger external systems, and file uploads consume storage. Deleting a Custom Agent, revoking a token, and deleting a view/comment can have irreversible or externally visible consequences, so care is required before making these calls.  
  ↳ source:https://developers.notion.com/llms.txt

---
*Provenance:Verified on 2026-09-17*

<!-- NOTICE:BEGIN v2026-10-01 -->
## Notices
1. This dossier is a compilation of facts drawn from publicly available information.
2. Quoted excerpts remain the property of their respective rights holders.
3. Content marked as self-described is the company's own statement, not a conclusion we have verified.
4. All trademarks are the property of their respective owners.
<!-- NOTICE:END -->

{
  "_schema": "api_provider_report/v1",
  "_stage": "completed",
  "A_identity": {
    "slug": "notion",
    "name": "Notion",
    "official_website": "https://www.notion.com",
    "doc_url": {
      "value": "https://developers.notion.com",
      "source_url": "https://developers.notion.com",
      "not_found": false
    }
  },
  "B_positioning": {
    "company_positioning": "Notion is an all-in-one AI workspace that brings notes, documents, wikis, projects, tasks, and databases together on one platform, and provides AI capabilities such as Notion AI, Custom Agents, AI Meeting Notes, and Enterprise Search, allowing teams to work alongside agents on their day-to-day work. The website describes it as “Where teams and agents think together,” emphasizing capturing knowledge, finding answers instantly, and automating busywork. The company says it is used by 98% of Forbes Cloud 100 companies. The company is headquartered in San Francisco, and its team has backgrounds in computing, history, art, programming languages, and other fields.",
    "api_overall_role": "Notion’s developer platform centers on a REST API (base URL https://api.notion.com), through which “connections” link workspaces with external SaaS products, automation scripts, or custom-built tools and enable programmatic reading and writing of workspace content. The API supports reading, creating, and updating nearly all object types—pages, databases/data sources, users, comments, views, files, and blocks—and subscribing to real-time events via webhooks. Several product lines build on the same authentication framework: Agent APIs (to start sessions with Custom Agents), Agent Skills API (to download skills stored in Notion), Notion MCP (to connect MCP clients to workspaces), Workers (to run custom code/agent tools/syncs within Notion), CLI, and the enterprise-focused Admin API (for compliance, audits, legal holds, permission groups, and MCP/PAT management, among other things).",
    "business_logic": {
      "value": "Primarily subscription-based SaaS: Free / Plus / Business / Enterprise plans priced per member (seat), with monthly or annual billing (annual billing saves up to 20%), and AI, permissions, security, and compliance capabilities unlocked by plan. AI-related features use credits for billing (Custom Agents offer a free trial, then cost $10 / 1,000 monthly Notion credits; Workers consume credits starting October 15). The developer ecosystem is extended through public connections and the Marketplace; the API itself is not priced separately and is included with the plan.",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "target_users": {
      "value": "Developers, teams, and enterprises. Segments include developers who want to connect external tools to Notion or build internal automation (internal connection / PAT); third parties publishing SaaS products or services to many Notion users and workspaces (public connection, OAuth); and organizations handling enterprise-grade compliance, audits, and permission management (Admin API).",
      "source_url": "https://developers.notion.com",
      "not_found": false
    },
    "industries": [
      "data-analytics",
      "productivity-software"
    ]
  },
  "C_capabilities": {
    "api_surfaces": [
      {
        "base_url": "https://api.notion.com/v1",
        "capabilities": [
          {
            "name": "Notion Blocks API"
          },
          {
            "name": "Notion Comments API"
          },
          {
            "name": "Notion Databases API"
          },
          {
            "name": "Notion Pages API"
          },
          {
            "name": "Notion Search API"
          },
          {
            "name": "Notion Users API"
          }
        ]
      }
    ],
    "tag_hints": [
      "Collaboration",
      "Database",
      "Ideas",
      "Notes",
      "Productivity",
      "Project",
      "T1",
      "Task",
      "Wiki",
      "Workspace"
    ],
    "surface_caveat": "The 6 entries in apis[] are spec files split by tag and grouped under 1 base surface; they are not a list of independent products (count = specs, not products).",
    "action_list": {
      "value": "Create pages (POST /v1/pages, supporting Notion-flavored Markdown or children blocks); retrieve/update/move/trash pages; read/update page content as Markdown; query data sources; create/retrieve/update databases and data sources; list data source templates; append/retrieve/update/delete block children; create/update/delete/retrieve/list comments; search by title (POST /v1/search); list/retrieve users and the bot user for the current token; create/send/complete/retrieve/list file uploads; create/retrieve/update/delete/list views and their queries; create and query AI meeting notes; manage Custom Agents (query/retrieve/insights/status/credit limit/delete/batch) and agent sessions (create, query, cancel, events); download Agent Skills plugins/skills; subscribe to webhook events (such as creation, update, and deletion of pages, databases/data sources, comments, file uploads, and views); Admin API (legal holds, permission groups, users, workspace exports, MCP connections, PAT management, agent governance, and credits policies).",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "fit_scenarios": {
      "value": "1) Sync data from external systems into Notion databases and keep it up to date (Workers Syncs); 2) use agents to automatically create/update pages, generate AI meeting notes, and organize comments and tasks; 3) after a user installs a public connection, automatically create databases, pages, and views in their workspace; 4) respond to page/database/comment changes in real time via webhooks to drive automated workflows; 5) use the Admin API for enterprise compliance audits, legal holds, and permission management.",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "unfit_scenarios": {
      "value": "Not suitable for high-frequency calls requiring extremely low latency or freedom from rate limits (600/180 requests per minute per connection, plus shared workspace-level rate limits); individual requests are subject to size limits (payloads of up to 1,000 blocks and 500 KB, rich-text strings/URLs of up to 2,000 characters, etc.), making it unsuitable for large files or bulk data transfer (large files must use multipart upload); not suitable as a general-purpose compute engine or for storage and computation outside Notion use cases.",
      "source_url": "https://developers.notion.com/reference/request-limits",
      "not_found": false
    }
  },
  "D_autonomy_gate": {
    "onboarding_signal": "self-serve",
    "public": false,
    "human_steps": {
      "value": "A Notion account and workspace are required; if a workspace picker appears when creating a token, a workspace must be selected first. On Business and Enterprise plans, PAT creation is restricted by default and must be enabled by a workspace owner under Settings → Connections. When creating a connection, an installation scope must be selected (Any workspace or Selected workspaces only; this cannot be changed after creation). Public connections also require end users to authorize accessible pages through a page picker in the OAuth flow.",
      "source_url": "https://developers.notion.com/guides/get-started/quick-start",
      "not_found": false
    },
    "self_serve_activation": {
      "value": "Individuals and developers can self-serve activation: in the Developer portal, open Personal access tokens → New token → enter a name and select the Notion API capability → Create token. Once the token is obtained, the API can be called directly with a Bearer header, with no OAuth or contract required. Internal connections can also be created on a self-serve basis. A Notion account/workspace is required, and some plans (Business/Enterprise) require an administrator to enable PAT creation first.",
      "source_url": "https://developers.notion.com/guides/get-started/quick-start",
      "not_found": false
    },
    "programmatic_payment": {
      "value": "No programmatic payment channel is provided. Notion currently accepts only major credit and debit cards. Plans are billed per member and settled on the billing cycle; the documentation does not mention API-based ordering or a self-serve payment method that does not require manually entering card details.",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "tos_agent_allowed": {
      "value": null,
      "source_url": null,
      "not_found": true
    }
  },
  "E_economics": {
    "pricing_model_signal": "freemium",
    "settlement_shape": {
      "value": "Primarily subscription-based: Free / Plus / Business / Enterprise plans billed per member (seat), with monthly or annual billing available (annual billing saves up to 20%) and prorated billing for changes in membership; supplemented by usage-based billing for Notion credits (AI features / Custom Agents / Workers); custom domains for sites and similar items are charged separately per domain.",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "free_tier": {
      "value": "A free tier is available: individual use includes unlimited pages and blocks, as well as basic forms/sites, Notion Calendar, databases (including subtasks/dependencies/custom properties), and more. Free workspaces shared by two or more members have a block limit (after reaching it, existing content can still be read, edited, and organized, but no new blocks can be added). Plus/Business/Enterprise offer trials of Notion AI and other features, along with higher quotas. The API itself is not priced separately and is included with the workspace plan.",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "unit_cost": {
      "value": "Custom Agents: free trial, then $10 per 1,000 monthly Notion credits; plans themselves are priced per member (seat), with specific rates listed on the pricing page; Workers consume Notion credits starting October 15.",
      "source_url": "https://www.notion.com/pricing",
      "not_found": false
    },
    "rate_limit": {
      "value": "Per 60-second window per connection: 600 requests per minute for Business/Enterprise (about 10/second), and 180 requests per minute for other plans (about 3/second). There is also a shared per-workspace rate limit across all connections in the workspace (which scales with the plan), so a single connection may be limited even if it has not exceeded its own limit. Exceeding the limit returns HTTP 429 with code \"rate_limited\" (with Retry-After; up to 60 seconds per connection, possibly longer per workspace); overload returns 529 \"service_overload\". Additional limits: payloads of up to 1,000 blocks and 500 KB.",
      "source_url": "https://developers.notion.com/reference/request-limits",
      "not_found": false
    }
  },
  "F_integration": {
    "delivery_model": "open-core",
    "callable_host": true,
    "surface_signals": [
      "Security",
      "RateLimits",
      "AgenticAccess",
      "OpenAPI",
      "Documentation",
      "JSONSchema"
    ],
    "auth_shape": {
      "value": "Authentication uses Bearer tokens and supports three authentication models: Internal connection (a static API token for a single workspace), Public connection (OAuth 2.0, with users selecting pages when granting access), and Personal access token (a user-level static bearer token). Requests must include the header Authorization: Bearer <token> and Notion-Version (e.g., 2026-03-11).",
      "source_url": "https://developers.notion.com",
      "not_found": false
    },
    "sdk": {
      "value": "Official JavaScript SDK: @notionhq/client (github.com/makenotion/notion-sdk-js). Documentation examples also provide cURL, HTTP, and JavaScript versions. There are also Notion CLI and Workers SDK (@notionhq/workers), and any language/library that supports HTTP can be used to make calls.",
      "source_url": "https://developers.notion.com/reference/intro",
      "not_found": false
    },
    "openapi_spec_url": {
      "value": "https://developers.notion.com/openapi.json",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    },
    "sandbox": {
      "value": null,
      "source_url": null,
      "not_found": true
    },
    "reversibility": {
      "value": "Most operations read or write workspace content and have relatively manageable side effects: pages/blocks can be updated, and deleting a page means trashing it (moving it to the trash). However, creating a comment notifies relevant users, subscribed webhooks trigger external systems, and file uploads consume storage. Deleting a Custom Agent, revoking a token, and deleting a view/comment can have irreversible or externally visible consequences, so care is required before making these calls.",
      "source_url": "https://developers.notion.com/llms.txt",
      "not_found": false
    }
  },
  "_provenance": {
    "verified_at": "2026-09-17"
  },
  "_notice": {
    "version": "2026-10-01",
    "lang": "en",
    "data_disclaimer": "The data in this dossier was retrieved, analyzed and summarized by AI agents, so gaps and errors cannot be ruled out. Information published on the web also changes over time, so please factor that uncertainty in when you use this data. We recommend verifying anything that matters against the source links provided in the dossier, supplemented by your own web research. If you find a discrepancy between this dossier and the facts, please tell us through the contact details on our website or in your purchase account; we also review and extend the data periodically.",
    "legal": [
      "This dossier is a compilation of facts drawn from publicly available information.",
      "Quoted excerpts remain the property of their respective rights holders.",
      "Content marked as self-described is the company's own statement, not a conclusion we have verified.",
      "All trademarks are the property of their respective owners."
    ]
  }
}

Coming soon.