better-notion

用途

better-notion 是一个面向 Notion 的技能，通过 Notion API 对页面（pages）、数据库（data sources）和区块（blocks）执行完整的 CRUD 操作，即创建、读取、更新、删除，并支持搜索与查询。

主要能力

• 搜索：调用 /v1/search 接口按标题等条件搜索内容。
• 读取页面：获取指定页面信息，以及获取页面的子区块。
• 创建页面：在数据库中创建页面，需指定父级 data_source_id 与属性。
• 查询数据库：对 data_sources 执行查询，支持 filter 过滤条件。
• 更新页面：修改页面属性，例如将状态改为 Done。
• 添加区块：向页面追加子区块，例如段落。
• 删除：删除页面或区块（移入回收站）。
• 恢复：将 archived 设为 false，从回收站恢复区块。

使用方式

1. 配置密钥：

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

1. 在 Notion 界面中将目标页面或数据库共享给你的集成。

2. 通过 curl 调用 API，基本形式：

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X POST "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

常用操作示例：

# Search
curl -X POST "https://api.notion.com/v1/search" -d '{"query": "title"}'

# Get page
curl "https://api.notion.com/v1/pages/{page_id}"

# Get page blocks
curl "https://api.notion.com/v1/blocks/{page_id}/children"

# Create page in database
curl -X POST "https://api.notion.com/v1/pages" -d '{
  "parent": {"data_source_id": "xxx"},
  "properties": {"Name": {"title": [{"text": {"content": "Item"}}]}}
}'

# Query database
curl -X POST "https://api.notion.com/v1/data_sources/{id}/query" -d '{
  "filter": {"property": "Status", "select": {"equals": "Active"}}
}'

# Update page
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" -d '{
  "properties": {"Status": {"select": {"name": "Done"}}}
}'

# Add blocks
curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" -d '{
  "children": [{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Text"}}]}}]
}'

# Delete page or block (moves to trash)
curl -X DELETE "https://api.notion.com/v1/blocks/{block_id}"

# Restore from trash (set archived to false)
curl -X PATCH "https://api.notion.com/v1/blocks/{block_id}" -d '{"archived": false}'

属性类型格式

类型	格式
Title	{"title": [{"text": {"content": "..."}}]}
Text	{"rich_text": [{"text": {"content": "..."}}]}
Select	{"select": {"name": "Option"}}
Multi-select	{"multi_select": [{"name": "A"}]}
Date	{"date": {"start": "2024-01-15"}}
Checkbox	{"checkbox": true}
Number	{"number": 42}
URL	{"url": "https://..."}

2025-09-03 API 说明

• 数据库在 API 中称为 data sources。
• 创建页面和查询均使用 data_source_id。
• data_source_id 可从搜索结果中的 id 字段获取。
• 速率限制：约每秒 3 次请求。

适用场景

适用于需要通过脚本或自动化方式管理 Notion 内容的场景，例如批量创建页面、查询数据库记录、更新页面属性、追加区块内容，以及删除或恢复区块等。

限制

• 需要有效的 Notion API 密钥，并在 Notion 界面中共享目标页面或数据库给集成。
• 速率限制约为每秒 3 次请求。
• 删除操作会将页面或区块移入回收站，而非永久删除。
• 其他未在资料中说明的功能、收费、价格或平台信息暂未提供。