name: notion-pro description: Complete Notion API skill with Python CLI tool — auto-pagination, recursive blocks, 429 retry, and agent operation strategies. version: 1.0.1 homepage: https://github.com/baixiaodev/notion-pro-skill metadata: {"clawdbot":{"emoji":"📝"}} env:

• NOTION_API_KEY: Notion integration API key (or configure in openclaw.json → skills.entries.notion-pro.apiKey)

---

Notion Pro — Complete Notion API Skill for OpenClaw#

A production-grade Notion API skill with a built-in Python CLI tool. Unlike basic Notion skills that only provide command syntax, this skill includes agent operation strategies, automatic pagination, recursive block fetching, 429 rate-limit retry, and comprehensive API reference — everything an AI agent needs to operate Notion effectively.

What Makes This Different#

CapabilityThis SkillBasic SkillsAgent operation strategy (5-step workflow)✅❌Recursive block fetching ( --recursive, 5 levels)✅❌Auto-pagination ( --all)✅❌429 rate-limit auto-retry (Retry-After)✅❌Positional insert ( --after)✅❌API limits quick reference✅ CompletePartial4 operation pattern SOPs✅❌Zero dependencies (stdlib only)✅ Python 3Node.js / curl

Setup#

1. Create a Notion Integration and copy the API key

2. Configure the key via one of:

   • Environment variable: export NOTION_API_KEY="ntn_xxxxx"
   • OpenClaw config: openclaw.json → skills.entries.notion-pro.apiKey

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

4. If a page/database isn't found via search, it likely hasn't been shared with the integration yet

Tool: notion_api.py#

All Notion operations must go through this script — do not use curl directly.

Script path: scripts/notion_api.py (relative to this skill's directory)

bash

# The script auto-detects its own location. Usage:
python3 <SKILL_DIR>/scripts/notion_api.py <command> [options]

---

Agent Operation Strategy (Must Read)#

Task Planning Workflow#

Follow this sequence for any Notion task:

1. Discover — Use search to find the target page/database ID
2. Inspect — Use get-page or get-blocks to understand current structure
3. Plan — Determine the operation sequence (create/update/append/delete)
4. Execute — Execute in batches, ≤50 blocks per batch (safety margin)
5. Verify — After critical operations, use get-blocks to verify results

Read Strategy#

• Search before read: Never guess IDs — use search to find the exact page/database
• Recursively read nested content: get-blocks only returns direct children. If a block has has_children: true, you must call get-blocks again with that block's ID to get nested content. Or use --recursive for automatic traversal.
• Handle pagination: If response contains has_more: true, make multiple calls. Use --all for automatic pagination.

Write Strategy#

• Split long text: A single rich_text element's text.content is limited to 2000 characters. Split longer content into multiple paragraph blocks.
• Batch writes: One append-blocks call supports up to 100 block elements. Split into multiple calls if needed.
• Replace = Delete + Append: Notion API has no "replace block content" endpoint. To replace content: delete-block old blocks, then append-blocks new content at the correct position.
• Insert position: append-blocks appends to the end by default. To insert at a specific position, use --after with the preceding block's ID.

Database Write Strategy#

• Schema-First: Before creating a page, use get-page or query-database to inspect the database's property schema. Ensure your properties JSON matches.
• Title is required: Every database has exactly one title property — it must be provided when creating a page.
• Exact property names: Property names are case-sensitive and space-sensitive.

---

API Limits Quick Reference#

LimitValueRate limit3 requests/sec (average), returns 429 when exceededMax request payload500 KBMax blocks per payload1000 blocksMax array elements (blocks/rich_text)100rich_text text.content2000 charactersrich_text text.link.url2000 charactersURL property2000 charactersmulti_select options100relation linked pages100Database schema recommended size**≤ 50 KBPagination default/max page_size100**

429 handling: When rate-limited, the script automatically reads the Retry-After header and retries (up to 3 times). For manual batch operations, add 300–500ms between calls.

---

Command Reference#

Search#

bash

python3 scripts/notion_api.py search --query "keyword"
python3 scripts/notion_api.py search --query "keyword" --filter page
python3 scripts/notion_api.py search --query "keyword" --filter database --page-size 20

# Pagination (use next_cursor from previous response)
python3 scripts/notion_api.py search --query "keyword" --start-cursor "xxx"

# Auto-fetch all results (auto-paginates, may take time for large datasets)
python3 scripts/notion_api.py search --query "keyword" --all

Read Page#

bash

# Get page metadata (properties, parent, URL, etc.)
python3 scripts/notion_api.py get-page --page-id "xxx-xxx"

# Get page content (blocks) — check has_children for recursive fetching
python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx"

# Recursively fetch full page (auto-expands all nested blocks, max depth 5)
python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx" --recursive

# Pagination
python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx" --start-cursor "xxx"

Query Database#

bash

# Get all rows
python3 scripts/notion_api.py query-database --database-id "xxx"

# With filter
python3 scripts/notion_api.py query-database \
  --database-id "xxx" \
  --filter '{"property": "Status", "select": {"equals": "Active"}}'

# With sort
python3 scripts/notion_api.py query-database \
  --database-id "xxx" \
  --sorts '[{"property": "Date", "direction": "descending"}]'

# Compound filter (AND/OR)
python3 scripts/notion_api.py query-database \
  --database-id "xxx" \
  --filter '{"and": [{"property": "Status", "select": {"equals": "Active"}}, {"property": "Priority", "select": {"equals": "High"}}]}'

# Pagination
python3 scripts/notion_api.py query-database --database-id "xxx" --start-cursor "xxx"

# Auto-fetch all results
python3 scripts/notion_api.py query-database --database-id "xxx" --all

Create Page#

bash

# Create in database (properties must match schema)
python3 scripts/notion_api.py create-page \
  --parent-id "database_id" \
  --parent-type database \
  --properties '{"Name": {"title": [{"text": {"content": "New Entry"}}]}}'

# Create sub-page with content
python3 scripts/notion_api.py create-page \
  --parent-id "page_id" \
  --parent-type page \
  --properties '{"title": {"title": [{"text": {"content": "Sub-page Title"}}]}}' \
  --children '[{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello World"}}]}}]'

Update Page Properties#

bash

python3 scripts/notion_api.py update-page \
  --page-id "xxx" \
  --properties '{"Status": {"select": {"name": "Done"}}}'

Append Blocks#

bash

# Append to end (default)
python3 scripts/notion_api.py append-blocks \
  --block-id "page_id" \
  --children '[{"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Title"}}]}}, {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Body text"}}]}}]'

# Insert after a specific block
python3 scripts/notion_api.py append-blocks \
  --block-id "page_id" \
  --after "target_block_id" \
  --children '[{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Inserted here"}}]}}]'

Delete Block#

bash

python3 scripts/notion_api.py delete-block --block-id "block_id"

---

Block Type Reference#

Common Blocks (Creatable)#

json

// Paragraph
{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Text"}}]}}

// Headings
{"object": "block", "type": "heading_1", "heading_1": {"rich_text": [{"text": {"content": "H1"}}]}}
{"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "H2"}}]}}
{"object": "block", "type": "heading_3", "heading_3": {"rich_text": [{"text": {"content": "H3"}}]}}

// Toggleable heading (click to expand/collapse children)
{"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Title"}}], "is_toggleable": true}}

// Lists
{"object": "block", "type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": "Item"}}]}}
{"object": "block", "type": "numbered_list_item", "numbered_list_item": {"rich_text": [{"text": {"content": "Item"}}]}}

// To-do
{"object": "block", "type": "to_do", "to_do": {"rich_text": [{"text": {"content": "Task"}}], "checked": false}}

// Quote
{"object": "block", "type": "quote", "quote": {"rich_text": [{"text": {"content": "Quote text"}}]}}

// Callout
{"object": "block", "type": "callout", "callout": {"rich_text": [{"text": {"content": "Important note"}}], "icon": {"type": "emoji", "emoji": "⚠️"}}}

// Code
{"object": "block", "type": "code", "code": {"rich_text": [{"text": {"content": "print('hello')"}}], "language": "python"}}

// Divider
{"object": "block", "type": "divider", "divider": {}}

// Toggle
{"object": "block", "type": "toggle", "toggle": {"rich_text": [{"text": {"content": "Expandable"}}]}}

// Bookmark
{"object": "block", "type": "bookmark", "bookmark": {"url": "https://example.com"}}

// Equation
{"object": "block", "type": "equation", "equation": {"expression": "E = mc^2"}}

Block Types Supporting Nested Children#

These block types can contain children (use append-blocks to add child content):

• paragraph, bulleted_list_item, numbered_list_item, to_do
• quote, callout, toggle
• heading_1/2/3 (only when is_toggleable: true)
• column, synced_block, table

Types Not Creatable/Modifiable via API#

• link_preview — read-only
• meeting_notes / transcription — read-only
• synced_block — cannot update content
• template — creation deprecated
• table.table_width — immutable after creation

---

Rich Text Advanced Formatting#

json

// Bold + Italic
{"text": {"content": "Emphasis"}, "annotations": {"bold": true, "italic": true}}

// Code style
{"text": {"content": "variable"}, "annotations": {"code": true}}

// With link
{"text": {"content": "Click here", "link": {"url": "https://example.com"}}}

// Color (text/background)
{"text": {"content": "Colored"}, "annotations": {"color": "red"}}
// Available colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red
// Background: gray_background, brown_background, ..., red_background

// Mention page
{"type": "mention", "mention": {"type": "page", "page": {"id": "page-id"}}}

// Mention date
{"type": "mention", "mention": {"type": "date", "date": {"start": "2026-03-22"}}}

---

Property Type Reference#

json

{"title": [{"text": {"content": "..."}}]}           // Title (required, one per database)
{"rich_text": [{"text": {"content": "..."}}]}        // Rich text
{"select": {"name": "Option"}}                        // Select
{"multi_select": [{"name": "A"}, {"name": "B"}]}     // Multi-select
{"date": {"start": "2026-01-15"}}                     // Date
{"date": {"start": "2026-01-15", "end": "2026-01-20"}} // Date range
{"checkbox": true}                                     // Checkbox
{"number": 42}                                         // Number
{"url": "https://..."}                                 // URL
{"email": "a@b.com"}                                   // Email
{"phone_number": "+1-555-xxxx"}                        // Phone
{"relation": [{"id": "page_id"}]}                     // Relation
{"status": {"name": "In Progress"}}                   // Status
{"people": [{"id": "user_id"}]}                       // People

Read-only properties (not writable via API): formula, rollup, created_time, created_by, last_edited_time, last_edited_by, unique_id

---

Common Operation Patterns#

Pattern 1: Bulk Knowledge Base Population#

Scenario: Batch-write entries to a Notion knowledge base (database)

text

1. search → find database ID
2. query-database → get schema and existing entries (avoid duplicates)
3. For each entry:
   a. create-page → create page (properties match schema)
   b. append-blocks → batch-append content (≤50 blocks per batch)
   c. sleep 300ms between batches to avoid 429
4. query-database to verify entry count

Pattern 2: Page Content Update#

Scenario: Replace or supplement parts of an existing page

text

1. get-blocks → read all current blocks and their IDs
2. Identify the block ID range to replace
3. delete-block → delete old blocks one by one
4. append-blocks → append new content at correct position
Note: There is no "replace block" API — only delete + append

Pattern 3: Recursive Full-Page Read#

Scenario: Retrieve complete page content including nested toggles/lists

text

# Recommended: one command to recursively expand (max depth 5)
get-blocks --block-id <page_id> --recursive

# Manual layer-by-layer (for specific subtrees only):
1. get-blocks --block-id <page_id> → get top-level blocks
2. For blocks with has_children: true:
   get-blocks --block-id <block_id> → get children
3. Recurse until all levels are read
Note: --recursive auto-handles pagination and rate limiting (350ms interval)

Pattern 4: Conditional Query + Bulk Update#

Scenario: Filter specific entries and batch-update their properties

text

1. query-database --filter '...' → get matching page IDs
2. For each page ID:
   update-page --page-id <id> --properties '{"Status": {"select": {"name": "Done"}}}'
3. sleep 300ms between updates

---

API Version Notes (2025-09-03)#

• Databases → Data Sources: Query endpoint uses /data_sources/. The script auto-handles both.
• Dual IDs: Each database has both database_id and data_source_id
  • database_id: Used when creating pages ( parent: {"database_id": "..."})
  • data_source_id: Used for queries — the script handles this automatically
• Rate limit: ~3 requests/sec average
• Linked Databases: API cannot operate on linked database data sources — find the original
• Wiki Databases: Can only be created in Notion UI; API has limited read access

---

Important Reminders#

• Never confuse Notion with other platforms. Notion → api.notion.com. Different platforms have different APIs.
• Empty strings are invalid: To clear a property value, use null, not "".
• ID format is flexible: The API accepts UUIDs with or without hyphens.
• Pagination awareness: search and query-database return up to 100 items by default. For larger datasets, paginate via start_cursor or use --all.