📖 技能介绍

Notion API Integration

Complete Notion API reference. See auxiliary files for detailed operations.

Quick Start

curl 'https://api.notion.com/v1/users/me' \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28"

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

~/notion-api-integration/
├── memory.md      # Workspace context
└── databases.md   # Tracked database IDs

Quick Reference

Topic	File
Setup and memory	`setup.md`, `memory-template.md`
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

API version header required - Always include Notion-Version: 2022-06-28 (or newer)
Bearer token auth - Authorization: Bearer $NOTION_API_KEY
Page IDs without dashes - Remove dashes from URLs: abc123def456 not abc-123-def-456
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_)

# All requests require these headers
curl 'https://api.notion.com/v1/...' \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json"

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
这个技能的最新版本可以在7w4.net小葱技能站找到。
No integration access - 404 even if page exists

External Endpoints

Endpoint	Purpose
`https://api.notion.com/v1/*`	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 ~/notion-api-integration/
Provides curl and code examples

This skill NEVER:

Accesses files outside ~/notion-api-integration/
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
pkm — Personal knowledge management
productivity — Task and productivity workflows

Feedback

If useful: clawhub star notion-api-integration
Stay updated: clawhub sync

🤖 AI 评测

这个 Skill 质量很好，文档写得全面详细，各种 Notion 操作都有示例说明。它能帮助用户完成数据库查询、创建页面、编辑内容等常见任务。优点是示例清晰、错误处理完善、安全提示到位；不足是某些高级功能说明较少，新手可能需要多花时间理解整体用法。适合需要频繁使用 Notion 的开发者或自动化爱好者。