notion-api
Installation
Summary
Comprehensive REST API reference for reading, creating, updating, and deleting Notion content.
- Covers all core endpoints: pages, blocks, databases, data sources, users, and comments with curl examples and required headers
- Includes authentication via API key, rate limiting (3 req/sec average), request size limits, and pagination patterns
- Provides error handling reference (400, 401, 403, 404, 429, 500+ status codes) and exponential backoff strategy for rate limits
- Requires confirmation before destructive operations (updates, deletes, bulk creates) and enforces secure API key handling via environment variables
SKILL.md
Notion API Skill
This skill enables interaction with Notion workspaces through the Notion REST API. Use curl and jq for direct REST calls, or write ad-hoc scripts as appropriate for the task.
Authentication
API Key Handling
- Environment Variable: Check if
NOTION_API_TOKENis available in the environment - User-Provided Key: If the user provides an API key in context, use that instead
- No Key Available: If neither is available, use AskUserQuestion (or equivalent) to request the API key from the user
IMPORTANT: Never display, log, or send NOTION_API_TOKEN anywhere except in the Authorization header. Confirm its existence, ask if missing, use it in requests—but never echo or expose it.
Request Headers
All requests require these headers: