/notion-api

name: notion-api
description: >
  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.

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:

-H "Authorization: Bearer $NOTION_API_TOKEN" \
-H "Notion-Version: 2025-09-03" \
-H "Content-Type: application/json"

Verifying Authentication

Test the API key by retrieving the bot user:

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

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:

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

Filter values: `"page"` or `"data_source"` (or omit for both)

Pages

Retrieve a Page

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

**Note**: This returns page properties, not content. For content, use "Retrieve block children" with the page ID.

Create a Page

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq

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

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

Additional update options: `cover`, `is_locked`, `in_trash`

Archive (Delete) a Page

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

Retrieve a Page Property Item

For properties with more than 25 references:

curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Blocks (Page Content)

Retrieve Block Children

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Use the page ID as `block_id` to get page