用途:借助 Notion API 创建、读取、更新页面(pages)、数据源(databases,2025-09-03 版本中 API 称为 data sources)与块(blocks)。
使用准备:在 https://notion.so/my-integrations 创建集成,复制以 ntn_ 或 secret_ 开头的 API key,并保存到本地:mkdir -p ~/.config/notion 后执行 echo "ntn_your_key_here" > ~/.config/notion/api_key。需将目标页面或数据库共享给该集成(点击“...”→“Connect to”→集成名称)。
基本请求方式:所有请求需带 Authorization: Bearer 与 Notion-Version: 2025-09-03,以及 Content-Type: application/json 头,请求地址为 https://api.notion.com/v1/...。
主要能力:支持搜索页面与数据源(POST /v1/search);获取页面(GET /v1/pages/{page_id});获取页面内容块(GET /v1/blocks/{page_id}/children);在数据源中创建页面(POST /v1/pages);查询数据源(POST /v1/data_sources/{data_source_id}/query);创建数据源(POST /v1/data_sources);更新页面属性(PATCH /v1/pages/{page_id});向页面追加块(PATCH /v1/blocks/{page_id}/children)。
属性格式:支持标题、富文本、单选/多选、日期、复选框、数字、URL、Email、关联等常见属性类型。
版本差异:2025-09-03 中数据库改称数据源,需用 /data_sources/ 端点查询与检索;每个数据库同时具有 database_id 与 data_source_id,创建页面时用 database_id,查询时用 data_source_id;搜索结果中数据库以 "object": "data_source" 返回。
限制与注意:API 无法设置数据库视图筛选器(仅限 UI 操作);平均速率限制约 3 请求/秒;页面与数据库 ID 为 UUID(可含或不含连字符)。