Agent skill · writing content · intellectronica
notion-api
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.
Why this skill is useful
Provides specific commands and patterns for interacting with the Notion API that the AI wouldn't reliably generate on its own.
What it needs
Requires curl, jq installed locally. Requires notion account access. About 7k tokens when loaded. Last updated 2026-04-25. 281 stars on the source repository.
What this skill does
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 1. Environment Variable: Check if NOTIONAPITOKEN is available in the environment 2. User-Provided Key: If the user provides an API key in context, use that instead 3. 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 NOTIONAPITOKEN 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: Verifying Authentication Test the API key by retrieving the bot user: Base URL and Conventions Base URL: https://api.notion.com API Version: 2025-09-03 (required header) Data Format: JSON for all request/response bodies IDs: UUIDv4 format (dashes optional in requests) Timestamps: ISO 8601 format (2020-08-12T02:12:33.231Z) Property Names: snakecase Empty Values: Use null instead of empty strings Rate Limits Average: 3 requests per second per integration Bursts: Brief bursts above this limit are allowed Rate Limited Response: HTTP 429 with Retry-After header Strategy: Implement exponential backoff when receiving 429 responses Request Size Limits Type Limit ------ ------- Maximum block elements per payload 1000 Maximum payload size 500KB Rich text content 2000 characters URLs 2000 characters Equations 1000 characters Email addresses 200 characters Phone numbers 200 characters Multi-select options 100 items Relations 100 related pages People mentions 100 users Block arrays per request 100 elements Confirmation for Destructive Operations IMPORTANT: Before executing any operation that modifies or deletes data, ask the user for confirmation. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills intellectronica/skills--d0daf0