Notion: Full API Access for Pages, Databases, and Blocks Inside Your AI Agent

46,976 downloads, 165 stars, and 1,209 active installs. The Notion skill by @steipete is the most downloaded notes and PKM skill on ClawHub — by a wide margin. It gives your AI agent complete, authenticated access to the Notion API: pages, databases (now called "data sources"), blocks, and workspace search.

The author context matters here: steipete is Peter Steinberger, the founder of OpenClaw — the open-source agent framework that powers ClawHub. When the person who built the platform writes a skill, it tends to follow best practices that third-party authors miss. He has since joined OpenAI to work on agents, making this one of his last notable contributions to the ClawHub ecosystem.

If you've been bouncing between Notion's web UI and your terminal, this skill closes that gap.

The Problem It Solves

Notion is where a lot of teams keep their source of truth — project trackers, content calendars, CRMs, research databases. But accessing it programmatically has always meant writing your own API wrapper, handling auth, and figuring out Notion's quirky block structure.

The Notion skill handles all of that. Your agent gets native access to create entries, query filtered views, append rich content, and search across your workspace — in plain language, not JSON boilerplate.

How It Works

The skill wraps the Notion REST API with pre-configured curl commands and a structured data guide. It covers the full CRUD surface:

• Search across pages and databases
• Read page content as block trees
• Create pages inside databases
• Query databases with filters and sorts
• Update page properties
• Append blocks (paragraphs, lists, code blocks, etc.)
• Create new databases with custom schemas

Setup takes about 2 minutes:

# 1. Create an integration at https://notion.so/my-integrations
# 2. Copy the API key (starts with ntn_ or secret_)
mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key
 
# 3. Share your target pages/databases with the integration
#    (click "..." → "Connect to" → your integration name)

Every request uses this pattern:

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"

Deep Dive

Working with Pages

Search for pages across your workspace:

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": "Q1 Roadmap"}'

Fetch page content as blocks:

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

Append a paragraph block to any 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": "Agent note added at runtime."}}]}}
    ]
  }'

Working with Databases (Data Sources)

The Notion API 2025-09-03 version renamed "databases" to "data sources" — and introduced a split-ID system that catches many developers off guard.

Two IDs to know:

• database_id — used when creating a page inside a database
• data_source_id — used when querying or retrieving a database

Create a page in a database:

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 Task"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Query a database with filters:

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": "Due Date", "direction": "ascending"}]
  }'

Create a new database (data source) from scratch:

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": "Sprint Tracker"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "In Progress"}, {"name": "Done"}]}},
      "Due": {"date": {}}
    }
  }'

Property Type Reference

When creating or updating database entries, property values follow specific formats:

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"}]}

Real-World Use Cases

Project management automation — Query your sprint database for active tasks, update statuses based on code changes, append meeting notes as blocks to the relevant page.

Content calendar — Create entries for new blog posts with scheduled dates and statuses; update publish dates when content goes live.

AI-generated knowledge bases — Have your agent research a topic, then create a structured database entry with source URLs, summaries, and tags.

CRM workflows — Log customer interactions as timestamped blocks on a contact page; filter database by deal stage.

Comparison

Considerations

• Integration scoping — The integration can only access pages you've explicitly shared with it. If your agent can't find a page, it's almost certainly a sharing issue, not an API error.
• Rate limit — ~3 requests/second average. For batch operations, your agent should space requests.
• View filters — The API can query with filters but can't create or modify database views. Those remain UI-only.
• Block depth — Nested blocks are not returned by default; you need recursive calls to retrieve deeply nested content.
• Token overhead — The skill includes property type reference tables. On simple tasks this is overhead; on complex database work it pays off.

The Bigger Picture

Notion's adoption as a team knowledge base has made it a natural target for AI agent workflows. The version 2025-09-03 update (data sources, split IDs) was a breaking change that many tutorials still get wrong. The Notion skill bakes in the correct patterns — so your agent hits the right endpoints the first time instead of debugging 400 errors.

At 46,000+ downloads, this is one of the most-used OpenClaw skills period. The combination of Notion's flexible block model and an AI agent that can both read and write to it opens up genuine workflow automation — not just Q&A over static content.

View the skill on ClawHub: notion