This Claude skill integrates the Notion API to provide seamless management of Notion workspaces. It enables users to programmatically create, read, update, and organize pages, databases (data sources), and content blocks. Supporting the latest 2025-09-03 API version, it allows for sophisticated data manipulation, including handling complex property types like relations, multi-selects, and rich text, making it an essential tool for automating documentation and knowledge management.

When should I use notion?

notion is useful in the following scenarios: • 1. Automated Documentation: Automatically generate and structure project wikis, meeting notes, or research summaries directly into Notion pages. • 2. Database & CRM Management: Create and query structured databases to track tasks, manage leads, or maintain inventory with real-time property updates. • 3. Content Archiving: Append new information, paragraphs, or media blocks to existing pages to build a comprehensive and evolving internal knowledge repository. • 4. Workflow Automation: Synchronize data from external sources into Notion by programmatically updating page statuses, dates, and checkboxes.

name	notion
description	Notion API for creating and managing pages, databases, and blocks.
homepage	https://developers.notion.com
metadata	{"clawdbot":{"emoji":"📝"}}

notion

Use the Notion API to create/read/update pages, data sources (databases), and blocks.

Setup

Create an integration at https://notion.so/my-integrations
Copy the API key (starts with ntn_ or secret_)
Store it:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)

API Basics

All requests need:

NOTION_KEY=$(cat ~/.config/notion/api_key)
curl -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Note: The Notion-Version header is required. This skill uses 2025-09-03 (latest). In this version, databases are called "data sources" in the API.

Common Operations

Search for pages and data sources:

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

Get page:

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

Get page content (blocks):

curl "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03"

Create page in a data source:

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Query a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

Create a data source (database):

curl -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Update page properties:

curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Add blocks to page:

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
    ]
  }'

Property Types

Common property formats for database items:

Title: {"title": [{"text": {"content": "..."}}]}
Rich text: {"rich_text": [{"text": {"content": "..."}}]}
Select: {"select": {"name": "Option"}}
Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
Date: {"date": {"start": "2024-01-15", "end": "2024-01-16"}}
Checkbox: {"checkbox": true}
Number: {"number": 42}
URL: {"url": "https://..."}
Email: {"email": "a@b.com"}
Relation: {"relation": [{"id": "page_id"}]}

Key Differences in 2025-09-03

Databases → Data Sources: Use /data_sources/ endpoints for queries and retrieval
Two IDs: Each database now has both a database_id and a data_source_id
- Use database_id when creating pages (parent: {"database_id": "..."})
- Use data_source_id when querying (POST /v1/data_sources/{id}/query)
Search results: Databases return as "object": "data_source" with their data_source_id
Parent in responses: Pages show parent.data_source_id alongside parent.database_id
Finding the data_source_id: Search for the database, or call GET /v1/data_sources/{data_source_id}

Notes

Page/database IDs are UUIDs (with or without dashes)
The API cannot set database view filters — that's UI-only
Rate limit: ~3 requests/second average
Use is_inline: true when creating data sources to embed them in pages

notion

When & Why to Use This Skill

Use Cases

notion

Setup

API Basics

Common Operations

Property Types

Key Differences in 2025-09-03

Notes