OpenSkillIndex← back to search
claude-code

Skillshub notion-api

install
source · Clone the upstream repo
git clone https://github.com/ComeOnOliver/skillshub
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/ComeOnOliver/skillshub "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/intellectronica/agent-skills/notion-api" ~/.claude/skills/comeonoliver-skillshub-notion-api-d144da && rm -rf "$T"
manifest: skills/intellectronica/agent-skills/notion-api/SKILL.md
source content

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

TypeLimit
Maximum block elements per payload1000
Maximum payload size500KB
Rich text content2000 characters
URLs2000 characters
Equations1000 characters
Email addresses200 characters
Phone numbers200 characters
Multi-select options100 items
Relations100 related pages
People mentions100 users
Block arrays per request100 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 content. Check 
has_children
on each block for nested content.

Append Block Children

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq

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

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

Update a Block

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq

The update replaces the entire value for the specified field.

Delete a Block

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

Moves block to trash (can be restored).

Databases

Retrieve a Database

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

Returns database structure including data sources and properties.

Query a Database

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

See 

references/filters-and-sorts.md
for comprehensive filter and sort documentation.

Create a Database

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq

Update a Database

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq

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

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq

Users

List All Users

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

Retrieve a User

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

Retrieve Bot User (Self)

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

Comments

Retrieve Comments

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

Use a page ID as 

block_id
for page-level comments.

Create a Comment

On a page:

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq

Reply to a discussion:

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq

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:

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

Error Handling

HTTP StatusCodeDescription
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