notion

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

配置

1. 在 https://notion.so/my-integrations 创建一个集成（integration）
2. 复制 API 密钥（以 ntn_ 或 secret_ 开头）
3. 将其保存至本地：

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

4. 将目标页面或数据源共享给你的集成（点击 “...” → “Connect to” → 选择你的集成名称）

API 基础

所有请求均需包含以下参数：

NOTION_KEY=$(cat ~/.config/notion/api_key)
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 将数据库称为 “data sources”（数据源）。

常用操作

搜索页面与数据源：

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"}'

获取页面信息：

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

获取页面内容（块）：

curl "https://api.notion.com/v1/blocks/{page_id}/children" 
  -H "Authorization: Bearer $NOTION_KEY" 
  -H "Notion-Version: 2025-09-03"

在数据源中创建页面：

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"}}
    }
  }'

查询数据源（数据库）：

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_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"}]
  }'

创建数据源（数据库）：

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": {}}
    }
  }'

更新页面属性：

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"}}}}'

向页面添加块：

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（标题）： {"title": [{"text": {"content": "..."}}]}
• Rich text（富文本）： {"rich_text": [{"text": {"content": "..."}}]}
• Select（单选）： {"select": {"name": "Option"}}
• Multi-select（多选）： {"multi_select": [{"name": "A"}, {"name": "B"}]}
• Date（日期）： {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
• Checkbox（复选框）： {"checkbox": true}
• Number（数字）： {"number": 42}
• URL（网址）： {"url": "https://..."}
• Email（邮箱）： {"email": "a@b.com"}
• Relation（关联）： {"relation": [{"id": "page_id"}]}

2025-09-03 版本的关键变更

• 数据库 → 数据源（Databases → Data Sources）： 查询与检索请使用 /data_sources/ 相关端点
• 两种 ID： 每个数据库现在同时拥有 database_id 和 data_source_id
  • 创建页面时使用 database_id（例如：parent: {"database_id": "..."}）
  • 查询数据源时使用 data_source_id（例如：POST /v1/data_sources/{id}/query）
• 搜索结果： 数据源在响应中以 "object": "data_source" 形式返回，并附带其 data_source_id
• 响应中的 parent 字段： 页面对象会同时包含 parent.data_source_id 和 parent.database_id
• 如何获取 data_source_id： 可通过搜索定位该数据源，或调用 GET /v1/data_sources/{data_source_id}

注意事项

• 页面与数据库 ID 均为 UUID 格式（可含或不含短横线）
• API 不支持设置数据库视图（view）的筛选条件——该功能仅限 UI 界面操作
• 速率限制：平均约 3 次请求/秒
• 创建数据源时指定 is_inline: true 可将其内嵌至页面中