Notion API Integration
Complete Notion API reference. See auxiliary files for detailed operations.
Quick Start
CODEBLOCK0
Setup
On first use, read setup.md. Preferences stored in ~/notion-api-integration/memory.md.
When to Use
Any Notion operation: databases, pages, blocks, users, search, comments, properties.
Architecture
CODEBLOCK1
Quick Reference
| Topic | File |
|---|
| Setup and memory | INLINECODE2 , INLINECODE3 |
| Databases: query, create, update |
databases.md |
| Pages: CRUD, properties |
pages.md |
| Blocks: content, children |
blocks.md |
| Property types reference |
properties.md |
| Filters and sorts |
filters.md |
| Search and users |
search.md |
| Pagination patterns |
pagination.md |
| Error handling |
errors.md |
Core Rules
- 1. API version header required - Always include
Notion-Version: 2022-06-28 (or newer) - Bearer token auth - INLINECODE13
- Page IDs without dashes - Remove dashes from URLs:
abc123def456 not INLINECODE15 - Property names are case-sensitive - Match exactly as defined in database
- Pagination mandatory - Use
start_cursor for results over 100 items - Rate limits - 3 requests/second average, burst allowed
- Integration access - Pages must be shared with integration to access
Authentication
Required environment variable:
- -
NOTION_API_KEY - Internal integration token (starts with ntn_ or secret_)
CODEBLOCK2
Common Traps
- - Missing
Notion-Version header - 400 error - Page ID with dashes - 404 not found
- Property name mismatch - Silent failure or error
- Skipping pagination - Miss data beyond first 100
- No integration access - 404 even if page exists
External Endpoints
| Endpoint | Purpose |
|---|
| INLINECODE21 | All Notion API operations |
No other endpoints are accessed.
Security & Privacy
Environment variable used:
- -
NOTION_API_KEY - for API authentication
Sent to Notion: Database queries, page content, block updates via api.notion.com
Stays local: API key (in environment variable only), ~/notion-api-integration/ preferences
Never: Store API keys in files, access pages not shared with integration
Scope
This skill ONLY:
- - Makes requests to api.notion.com endpoints
- Stores preferences in INLINECODE23
- Provides curl and code examples
This skill NEVER:
- - Accesses files outside INLINECODE24
- Makes requests to other endpoints
- Stores API keys in files
Trust
By using this skill, data is sent to Notion (notion.com).
Only install if you trust Notion with your workspace data.
Related Skills
Install with
clawhub install <slug> if user confirms:
- -
api — REST API patterns - INLINECODE27 — Personal knowledge management
- INLINECODE28 — Task and productivity workflows
Feedback
- - If useful: INLINECODE29
- Stay updated: INLINECODE30
Notion API 集成
完整的 Notion API 参考文档。详细操作请参见辅助文件。
快速开始
bash
curl https://api.notion.com/v1/users/me \
-H Authorization: Bearer $NOTIONAPIKEY \
-H Notion-Version: 2022-06-28
设置
首次使用时，请阅读 setup.md。偏好设置存储在 ~/notion-api-integration/memory.md 中。
使用场景
任何 Notion 操作：数据库、页面、块、用户、搜索、评论、属性。
架构
~/notion-api-integration/
├── memory.md # 工作区上下文
└── databases.md # 追踪的数据库 ID
快速参考
| 主题 | 文件 |
|---|
| 设置与记忆 | setup.md、memory-template.md |
| 数据库：查询、创建、更新 |
databases.md |
| 页面：增删改查、属性 | pages.md |
| 块：内容、子块 | blocks.md |
| 属性类型参考 | properties.md |
| 筛选与排序 | filters.md |
| 搜索与用户 | search.md |
| 分页模式 | pagination.md |
| 错误处理 | errors.md |
核心规则
- 1. 需要 API 版本头 - 始终包含 Notion-Version: 2022-06-28（或更新版本）
- Bearer 令牌认证 - Authorization: Bearer $NOTIONAPIKEY
- 页面 ID 不含连字符 - 从 URL 中移除连字符：使用 abc123def456 而非 abc-123-def-456
- 属性名称区分大小写 - 必须与数据库中定义完全一致
- 必须分页 - 超过 100 条结果时使用 start_cursor
- 速率限制 - 平均每秒 3 个请求，允许突发
- 集成访问权限 - 页面必须与集成共享才能访问
认证
所需环境变量：
- - NOTIONAPIKEY - 内部集成令牌（以 ntn 或 secret 开头）
bash
所有请求都需要这些头信息
curl https://api.notion.com/v1/... \
-H Authorization: Bearer $NOTION
APIKEY \
-H Notion-Version: 2022-06-28 \
-H Content-Type: application/json
常见陷阱
- - 缺少 Notion-Version 头 - 返回 400 错误
- 页面 ID 包含连字符 - 返回 404 未找到
- 属性名称不匹配 - 静默失败或报错
- 跳过分页 - 丢失前 100 条之后的数据
- 无集成访问权限 - 即使页面存在也返回 404
外部端点
| 端点 | 用途 |
|---|
| https://api.notion.com/v1/* | 所有 Notion API 操作 |
不访问其他端点。
安全与隐私
使用的环境变量：
- - NOTIONAPIKEY - 用于 API 认证
发送至 Notion： 数据库查询、页面内容、块更新（通过 api.notion.com）
本地保留： API 密钥（仅限环境变量）、~/notion-api-integration/ 偏好设置
绝不： 将 API 密钥存储在文件中、访问未与集成共享的页面
范围
此技能仅：
- - 向 api.notion.com 端点发送请求
- 将偏好设置存储在 ~/notion-api-integration/ 中
- 提供 curl 和代码示例
此技能绝不：
- - 访问 ~/notion-api-integration/ 之外的文件
- 向其他端点发送请求
- 将 API 密钥存储在文件中
信任
使用此技能即表示数据将被发送至 Notion（notion.com）。
仅当您信任 Notion 处理您的工作区数据时才安装。
相关技能
如果用户确认，使用 clawhub install
安装：
- - api — REST API 模式
- pkm — 个人知识管理
- productivity — 任务与生产力工作流
反馈
- - 如果觉得有用：clawhub star notion-api-integration
- 保持更新：clawhub sync
