Notion 知识管理

通过 curl 操作 Notion API：页面、数据库、块、搜索

Notion API

通过 curl 调用 Notion API，创建、读取、更新页面、数据库（数据源）和块。无需额外工具——仅需 curl 和 Notion API key。

前置条件

在 https://notion.so/my-integrations 创建集成

复制 API key（以 ntn_ 或 secret_ 开头）

存入 ~/.hermes/.env：

   NOTION_API_KEY=ntn_your_key_here

重要：在 Notion 中将目标页面/数据库分享给集成（点击"..." → "连接到" → 你的集成名称）

API 基础

所有请求使用此模式：

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Notion-Version 请求头是必须的。本技能使用 2025-09-03（最新版）。该版本中，API 将 database 称为 "data source"。

常用操作

搜索

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "页面标题"}'

获取页面

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

获取页面内容（块）

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

在数据库中创建页面

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "新条目"}}]},
      "Status": {"select": {"name": "待办"}}
    }
  }'

查询数据库

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "状态", "select": {"equals": "进行中"}},
    "sorts": [{"property": "日期", "direction": "descending"}]
  }'

创建数据库

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_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": {}}
    }
  }'

更新页面属性

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"状态": {"select": {"name": "已完成"}}}}'

向页面添加内容

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "来自 Hermes 的问候！"}}]}}
    ]
  }'

属性类型

数据库条目的常见属性格式：

标题： {"title": [{"text": {"content": "..."}}]}

富文本： {"rich_text": [{"text": {"content": "..."}}]}

单选： {"select": {"name": "选项"}}

多选： {"multi_select": [{"name": "A"}, {"name": "B"}]}

日期： {"date": {"start": "2026-01-15", "end": "2026-01-16"}}

复选框： {"checkbox": true}

数字： {"number": 42}

URL： {"url": "https://..."}

邮箱： {"email": "user@example.com"}

关联： {"relation": [{"id": "page_id"}]}

API 版本 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

注意事项

页面/数据库 ID 是 UUID（可带或不带破折号）

速率限制：平均每秒约 3 次请求

API 无法设置数据库视图筛选器——那是 UI 专属功能

创建数据源时使用 is_inline: true 可将其嵌入页面中

为 curl 添加 -s 标志可隐藏进度条（Hermes 输出更清晰）

通过 jq 管道输出可读的 JSON：... | jq '.results[0].properties'