notion

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

设置

1. 1. 在 https://notion.so/my-integrations 创建一个集成
2. 复制API密钥（以ntn或secret开头）
3. 存储密钥：

bash
mkdir -p ~/.config/notion
echo ntnyourkeyhere > ~/.config/notion/apikey

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: xxx},
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: descending}]
}

创建数据源（数据库）：

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: [
{object: block, 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.databaseid旁边显示parent.datasourceid
• 查找datasourceid： 搜索数据库，或调用GET /v1/datasources/{datasource_id}

注意事项

• - 页面/数据库ID是UUID（带或不带连字符）
• API无法设置数据库视图过滤器——这仅限UI操作
• 速率限制：约3个请求/秒平均值
• 创建数据源时使用is_inline: true可将其嵌入页面中