openclaw-notion-api

使用 Notion API 创建/读取/更新页面、数据源（数据库）和块。

设置

1. 1. 在 https://www.notion.so/profile/integrations/internal 创建内部集成
2. 复制 API 密钥（以 ntn 或 secret 开头）
3. 存储密钥：

1. 4. 将目标页面/数据库与集成共享（点击 ... → 连接到 → 你的集成名称）

API 基础

所有请求都需要：
bash
NOTIONKEY=$(cat ~/.config/notion/apikey)
curl -X GET https://api.notion.com/v1/... \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json

注意： Notion-Version 请求头是必需的。本技能使用 2025-09-03（最新版本）。在此版本中，数据库在 API 中称为数据源。

常用操作

搜索页面和数据源：
bash
curl -X POST https://api.notion.com/v1/search \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {query: 页面标题}

获取页面：
bash
curl https://api.notion.com/v1/pages/{page_id} \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03

获取页面内容（块）：
bash
curl https://api.notion.com/v1/blocks/{page_id}/children \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03

在数据源中创建页面：
bash
curl -X POST https://api.notion.com/v1/pages \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {
parent: {database_id: xxxxxx},
properties: {
名称: {title: [{text: {content: 新项目}}]},
状态: {select: {name: 待办}}
}
}

查询数据源（数据库）：
bash
curl -X POST https://api.notion.com/v1/datasources/{datasource_id}/query \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {
filter: {property: 状态, select: {equals: 活跃}},
sorts: [{property: 日期, direction: 降序}]
}

创建数据源（数据库）：
bash
curl -X POST https://api.notion.com/v1/data_sources \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {
parent: {page_id: xxx},
title: [{text: {content: 我的数据库}}],
properties: {
名称: {title: {}},
状态: {select: {options: [{name: 待办}, {name: 完成}]}},
日期: {date: {}}
}
}

更新页面属性：
bash
curl -X PATCH https://api.notion.com/v1/pages/{page_id} \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {properties: {状态: {select: {name: 完成}}}}

向页面添加块：
bash
curl -X PATCH https://api.notion.com/v1/blocks/{page_id}/children \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: application/json \
-d {
children: [
{type: paragraph, paragraph: {rich_text: [{text: {content: 你好}}]}}
]
}

属性类型

数据库项的常用属性格式：

• - 标题： {title: [{text: {content: ...}}]}
• 富文本： {richtext: [{text: {content: ...}}]}
• 选择： {select: {name: 选项}}
• 多选： {multiselect: [{name: A}, {name: B}]}
• 日期： {date: {start: 2024-01-15, end: 2024-01-16}}
• 复选框： {checkbox: true}
• 数字： {number: 42}
• URL： {url: https://...}
• 邮箱： {email: a@b.com}
• 关联： {relation: [{id: page_id}]}

2025-09-03 版本的关键差异

• - 数据库 → 数据源： 使用 /datasources/ 端点进行查询和检索
• 双 ID： 每个数据库现在同时拥有 databaseid 和 datasourceid

• - 搜索结果： 数据库以 object: datasource 形式返回，并带有其 datasourceid
• 响应中的父级： 页面显示 parent.datasourceid 以及 parent.databaseid
• 查找 datasourceid： 搜索数据库，或调用 GET /v1/datasources/{datasource_id}

文件上传

使用直接上传方法上传图片或文件到 Notion（文件大小不超过 20MB）。两者的步骤完全相同，仅在步骤 3 的块类型上有区别。

步骤 1：创建文件上传对象

创建上传对象以获取上传 URL：
bash
curl --request POST \
--url https://api.notion.com/v1/file_uploads \
-H Authorization: Bearer $NOTION_KEY \
-H Content-Type: application/json \
-H Notion-Version: 2025-09-03 \
--data {}

响应包含：

• - id：文件上传 ID（在步骤 3 中使用）
• upload_url：上传文件内容的 URL

步骤 2：上传文件内容

使用 multipart/form-data 上传实际的文件：
bash
curl --request POST \
--url https://api.notion.com/v1/fileuploads/{fileupload_id}/send \
-H Authorization: Bearer $NOTION_KEY \
-H Notion-Version: 2025-09-03 \
-H Content-Type: multipart/form-data \
-F file=@/path/to/file.png

重要：

• - 使用 POST 方法（不是 PUT）
• 包含 Authorization 和 Notion-Version 请求头
• 使用 -F 进行 multipart/form-data
• 文件大小必须 ≤ 20MB

步骤 3：插入到页面

将上传的文件作为块添加。根据文件类型选择不同的块类型：

上传图片：
bash
curl --request PATCH \
--url https://api.notion.com/v1/blocks/{page_id}/children \
-H Authorization: Bearer $NOTION_KEY \
-H Content-Type: application/json \
-H Notion-Version: 2025-09-03 \
--data {
children: [
{
type: image,
image: {
type: file_upload,
file_upload: {
id: {fileuploadid}