notion

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

设置

1. 1. 在 https://notion.so/my-integrations 创建一个集成
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: page title}

获取页面：
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: {
Name: {title: [{text: {content: New Item}}]},
Status: {select: {name: Todo}}
}
}

查询数据源（数据库）：
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: Status, select: {equals: Active}},
sorts: [{property: Date, 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: My Database}}],
properties: {
Name: {title: {}},
Status: {select: {options: [{name: Todo}, {name: Done}]}},
Date: {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: {Status: {select: {name: Done}}}}

向页面添加块：
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: Hello}}]}}
]
}

属性类型

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

• - 标题： {title: [{text: {content: ...}}]}
• 富文本： {richtext: [{text: {content: ...}}]}
• 选择： {select: {name: Option}}
• 多选： {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}

备注

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