📝 Notion — Notion

技能文档

Use the Notion API to create/read/update pages, data sources (databases), and blocks.

Setup

• 创建 integration 在 https://notion.所以/my-integrations
• 复制 API 键 (starts 带有 ntn_ 或 secret_)
• Store :

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

• 分享 target pages/databases 带有 integration (click "..." → "Connect 到" → integration name)

API Basics

All requests need:

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"

Note: The Notion-Version header is required. This skill uses 2025-09-03 (latest). In this version, databases are called "data sources" in the API.

Common Operations

搜索 对于 pages 和 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"}'

获取 page:

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

获取 page content (blocks):

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

创建 page 在...中 data source:

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

查询 data source (数据库):

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

创建 data source (数据库):

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

更新 page properties:

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

添加 blocks 到 page:

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

属性 Types

Common property formats for database items:

• Title: {"title": [{"text": {"content": "..."}}]}
• Rich text: {"rich_text": [{"text": {"content": "..."}}]}
• Select: {"select": {"name": "选项"}}
• Multi-select: {"multi_select": [{"name": ""}, {"name": "B"}]}
• 日期: {"日期": {"开始": "2024-01-15", "end": "2024-01-16"}}
• Checkbox: {"checkbox": 真}
• 数字: {"数字": 42}
• URL: {"url": "https://..."}
• Email: {"email": "@b.com"}
• Relation: {"relation": [{"id": "page_id"}]}

键 Differences 在...中 2025-09-03

• Databases → Data Sources: 使用 /data_sources/ endpoints 对于 queries 和 retrieval
• Two IDs: 每个 数据库 现在 有 both database_id 和 data_source_id

• 搜索 results: Databases return 作为 "对象": "data_source" 带有 data_source_id
• Parent 在...中 responses: Pages show parent.data_source_id alongside parent.database_id
• Finding data_source_id: 搜索 对于 数据库, 或 call 获取 /v1/data_sources/{data_source_id}

Notes

• Page/数据库 IDs UUIDs (带有 或 没有 dashes)
• API cannot 设置 数据库 视图 filters — 's UI-仅
• Rate limit: ~3 requests/第二个 平均值
• 使用 is_inline: 真 当...时 creating data sources 到 embed them 在...中 pages