notion-api

Notion API 技能

该技能支持通过Notion REST API与Notion工作区交互。使用curl和jq进行直接REST调用，或根据任务编写临时脚本。

身份验证

API 密钥处理

1. 环境变量：检查环境中是否存在NOTION_API_TOKEN
2. 用户提供的密钥：如果用户在上下文中提供了API密钥，则使用该密钥
3. 无可用密钥：如果两者都不可用，使用AskUserQuestion（或等效方法）向用户请求API密钥

重要：切勿在任何地方显示、记录或发送NOTION_API_TOKEN，除了在Authorization标头中。确认其存在，如果缺失则询问，在请求中使用它——但切勿回显或暴露它。

请求标头

所有请求都需要以下标头：

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

验证身份验证

通过检索机器人用户来测试API密钥：

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

基础URL和约定

• 基础URL：https://api.notion.com
• API版本：2025-09-03（必需标头）
• 数据格式：所有请求/响应体均为JSON
• ID：UUIDv4格式（请求中可省略短划线）
• 时间戳：ISO 8601格式（2020-08-12T02:12:33.231Z）
• 属性名称：snake_case
• 空值：使用null而非空字符串

速率限制

• 平均值：每个集成每秒3个请求
• 突发：允许短暂超过此限制的突发
• 速率限制响应：HTTP 429，带有Retry-After标头
• 策略：收到429响应时实现指数退避

请求大小限制

类型	限制
每个负载的最大块元素数	1000
最大负载大小	500KB
富文本内容	2000个字符
URL	2000个字符
公式	1000个字符
电子邮件地址	200个字符
电话号码	200个字符
多选选项	100项
关联	100个相关页面
人员提及	100个用户
每个请求的块数组	100个元素

破坏性操作的确认

重要：在执行任何修改或删除数据的操作之前，请向用户请求确认。这包括：

• 更新页面或块
• 删除/归档页面或块
• 修改数据库模式
• 创建页面（如果多个或批量）
• 任何批量操作

对于逻辑上的一组相关操作，一次确认即可。

核心API端点

搜索

搜索所有可访问的页面和数据库：

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "搜索词",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

筛选值："page"或"data_source"（或省略以同时搜索两者）

页面

检索页面

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

注意：这将返回页面属性，而非内容。要获取内容，请使用页面ID调用“检索块子项”。

创建页面

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "父页面ID"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "页面标题"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "段落内容"}}]
        }
      }
    ]
  }' | jq

父级选项：

• {"page_id": "..."} - 在页面下创建
• {"database_id": "..."} - 在数据库中创建（旧版）
• {"data_source_id": "..."} - 在数据源中创建（API v2025-09-03+）

更新页面

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "更新后的标题"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

其他更新选项：cover、is_locked、in_trash

归档（删除）页面

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

检索页面属性项

对于超过25个引用的属性：

curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

块（页面内容）

检索块子项

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

使用页面ID作为block_id来获取页面内容。检查每个块的has_children以获取嵌套内容。

追加块子项

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "新章节"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "此处内容"}}]
        }
      }
    ]
  }' | jq

每个请求最多100个块，最多2层嵌套。

请求体中的位置选项：

• 默认：追加到末尾
• "position": {"type": "start"} - 在开头插入
• "position": {"type": "after_block", "after_block": {"id": "block-id"}} - 在指定块后插入

检索块

curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

更新块

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "更新后的内容"}}]
    }
  }' | jq

更新将替换指定字段的整个值。

删除块

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

将块移至回收站（可恢复）。

数据库

检索数据库

curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

返回数据库结构，包括数据源和属性。

查询数据库

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "状态",
      "select": {"equals": "已完成"}
    },
    "sorts": [
      {"property": "创建时间", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

有关筛选和排序的完整文档，请参阅references/filters-and-sorts.md。

创建数据库

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "父页面ID"},
    "title": [{"type": "text", "text": {"content": "我的数据库"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "名称": {"title": {}},
        "状态": {
          "select": {
            "options": [
              {"name": "待办", "color": "red"},
              {"name": "进行中", "color": "yellow"},
              {"name": "已完成", "color": "green"}
            ]
          }
        },
        "截止日期": {"date": {}}
      }
    }
  }' | jq

更新数据库

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "更新后的标题"}}],
    "description": [{"text": {"content": "数据库描述"}}]
  }' | jq

数据源（API v2025-09-03+）

数据源是数据库中的单个表格。从API版本2025-09-03开始，数据库可以包含多个数据源。

创建数据源

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "数据库ID"},
    "title": [{"type": "text", "text": {"content": "新数据源"}}],
    "properties": {
      "名称": {"title": {}},
      "描述": {"rich_text": {}}
    }
  }' | jq

用户

列出所有用户

curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

检索用户

curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

检索机器人用户（自身）

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

评论

检索评论

curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

使用页面ID作为block_id获取页面级评论。

创建评论

在页面上：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "页面ID"},
    "rich_text": [{"type": "text", "text": {"content": "评论内容"}}]
  }' | jq

回复讨论：

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "讨论ID",
    "rich_text": [{"type": "text", "text": {"content": "回复内容"}}]
  }' | jq

注意：API无法启动新的内联讨论线程或编辑/删除现有评论。

分页

分页端点返回：

• has_more：布尔值，指示是否存在更多结果
• next_cursor：下一页的游标
• results：项目数组

要遍历所有结果：

1. 发起初始请求（省略start_cursor）
2. 检查响应中的has_more
3. 如果为true，提取next_cursor并将其作为start_cursor包含在下一个请求中
4. 重复直到has_more为false

带游标的请求示例：

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

错误处理

HTTP状态	代码	描述
400	invalid_json	请求体不是有效的JSON
400	invalid_request_url	URL格式错误
400	invalid_request	请求不受支持
400	validation_error	请求体与预期模式不匹配
400	missing_version	缺少Notion-Version标头
401	unauthorized	无效的Bearer令牌
403	restricted_resource	令牌缺少权限
404	object_not_found	资源不存在或未与集成共享
409	conflict_error	事务期间数据冲突
429	rate_limited	超出速率限制（检查Retry-After标头）
500	internal_server_error	意外的服务器错误
503	service_unavailable	Notion不可用或超过60秒超时
503	database_connection_unavailable	数据库无响应
504	gateway_timeout	请求超时

最佳实践

1. 存储ID：创建页面/数据库时，存储返回的ID以供将来更新
2. 使用属性ID：通过ID而非名称引用属性以保持稳定性
3. 批量操作：将多个小操作聚合到更少的请求中
4. 尊重速率限制：对429响应实现指数退避
5. 检查has_more：始终处理列表端点的分页
6. 更新前验证：在进行更新之前检索当前状态
7. 使用环境变量：切勿硬编码API密钥
8. 优雅处理错误：检查响应状态码和错误消息
9. 模式大小：保持数据库模式在50KB以下以获得最佳性能
10. 属性限制：具有超过25个页面引用的属性需要单独检索

参考

有关特定主题的详细文档，请参阅：

• references/block-types.md - 所有支持的块类型及其结构
• references/property-types.md - 数据库属性类型和值格式
• references/filters-and-sorts.md - 数据库查询筛选和排序语法
• references/rich-text.md - 富文本对象结构和注释