This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.
The notion-api skill provides a structured interface for interacting with Notion workspaces through the Notion REST API. It simplifies the process of reading, creating, updating, and deleting content within Notion, including pages, databases, blocks, comments, and other objects. By handling authentication, request headers, pagination, and error responses, this skill eliminates the complexity of manually managing REST calls, allowing users to focus on automating and integrating Notion workflows efficiently. Its emphasis on secure handling of API tokens ensures that sensitive credentials are never exposed, making it suitable for professional and personal projects alike.
The skill supports a wide range of Notion API operations, including retrieving user information, searching pages and databases, fetching page properties, and managing block content. It enforces best practices such as proper formatting for IDs, timestamps, and property names, as well as strict adherence to rate limits and request size constraints. Additional safeguards, like confirmation prompts for destructive operations, prevent accidental data loss. Users can utilize direct REST calls with curl and jq or implement custom scripts, making the skill flexible for different technical setups and programming environments.
Typical use cases include automating content updates, generating reports from Notion databases, syncing Notion pages with external systems, or building custom dashboards and integrations. Target users are developers, technical teams, and productivity enthusiasts who need programmatic access to Notion data. By providing clear instructions for authentication, request handling, and API interactions, this skill streamlines the process of integrating Notion into broader workflows and applications, improving efficiency and reducing the potential for errors.
You can provide the API token either through the environment variable NOTION_API_TOKEN or by supplying a user-provided key. The token must be used in the Authorization header and should never be logged or displayed.
This skill supports reading, creating, updating, and deleting pages, databases, blocks, comments, and other Notion content, with full coverage of endpoints and property formats.
Yes, the Notion API allows an average of 3 requests per second per integration, with brief bursts allowed. Receiving a 429 status requires implementing exponential backoff based on the Retry-After header.
Yes, before performing any updates, deletions, or bulk operations, the skill will request user confirmation to prevent accidental data loss.
IDs should be in UUIDv4 format (dashes optional), and timestamps must follow ISO 8601 format. Property names use snake_case, and empty values should be represented as null.
Quick Setup:
.claude/skills/Repository
intellectronica/agent-skills