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 c

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 NOTION API TOKEN 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 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: 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 : snake case 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. This includes: Updating pages or blocks Deleting/archiving pages or blocks Modifying database schemas Creating pages (if multiple or in batch) Any bulk operations For a logical group of related operations, a single confirmation is sufficient. Core API Endpoints Search Search across all accessible pages and databases: Filter values: "page" or "data source" (or omit for both) Pages Retrieve a Page Note : This returns page properties, not content. For content, use "Retrieve block children" with the page ID. Create a Page Parent options: {"page id": "..."} Create under a page {"database id": "..."} Create in a database (legacy) {"data source id": "..."} Create in a data source (API v2025 09 03+) Update a Page Additional update options: cover , is locked , in trash Archive (Delete) a Page Retrieve a Page Property Item For properties with more than 25 references: Blocks (Page Content) Retrieve Block Children Use the page ID as block id to get page content. Check has children on each block for nested content. Append Block Children Maximum 100 blocks per request, up to 2 levels of nesting. Position options in request body: Default: appends to end "position": {"type": "start"} Insert at beginning "position": {"type": "after block", "after block": {"id": "block id"}} Insert after specific block Retrieve a Block Update a Block The update replaces the entire value for the specified field. Delete a Block Moves block to trash (can be restored). Databases Retrieve a Database Returns database structure including data sources and properties. Query a Database See references/filters and sorts.md for comprehensive filter and sort documentation. Create a Database Update a Database Data Sources (API v2025 09 03+) Data sources are individual tables within a database. As of API version 2025 09 03, databases can contain multiple data sources. Create a Data Source Users List All Users Retrieve a User Retrieve Bot User (Self) Comments Retrieve Comments Use a page ID as block id for page level comments. Create a Comment On a page: Reply to a discussion: Note : The API cannot start new inline discussion threads or edit/delete existing comments. Pagination Paginated endpoints return: has more : Boolean indicating more results exist next cursor : Cursor for the next page results : Array of items To iterate through all results: 1. Make the initial request (omit start cursor ) 2. Check has more in the response 3. If true , extract next cursor and include it as start cursor in the next request 4. Repeat until has more is false Example request with cursor: Error Handling HTTP Status Code Description 400 invalid json Request body is not valid JSON 400 invalid request url URL is malformed 400 invalid request Request is not supported 400 validation error Request body doesn't match expected schema 400 missing version Missing Notion Version header 401 unauthorized Invalid bearer token 403 restricted resource Token lacks permission 404 object not found Resource doesn't exist or not shared with integration 409 conflict error Data collision during transaction 429 rate limited Rate limit exceeded (check Retry After header) 500 internal server error Unexpected server error 503 service unavailable Notion unavailable or 60s timeout exceeded 503 database connection unavailable Database unresponsive 504 gateway timeout Request timeout Best Practices 1. Store IDs : When creating pages/databases, store the returned IDs for future updates 2. Use Property IDs : Reference properties by ID rather than name for stability 3. Batch Operations : Aggregate multiple small operations into fewer requests 4. Respect Rate Limits : Implement exponential backoff for 429 responses 5. Check has more : Always handle pagination for list endpoints 6. Validate Before Updates : Retrieve current state before making updates 7. Use Environment Variables : Never hardcode API keys 8. Handle Errors Gracefully : Check response status codes and error messages 9. Schema Size : Keep database schemas under 50KB for optimal performance 10. Properties Limit : Properties with 25 page references require separate retrieval References For detailed documentation on specific topics, see: references/block types.md All supported block types and their structures references/property types.md Database property types and value formats references/filters and sorts.md Database query filter and sort syntax references/rich text.md Rich text object structure and annotations

notion-api