Notion

Notion page and database CRUD via API — create, read, update, and query Notion pages, data sources (databases), and blocks directly from CLI-JAW using the Notion API.

Quick Reference

Overview

The notion skill provides full CRUD access to Notion workspaces through the Notion API. It enables CLI-JAW to search for pages, create and update content, query databases (data sources), manage blocks, and apply visual design patterns — all without leaving the terminal.

Key capabilities:

• Search — find pages and data sources by title or content
• Read — retrieve page properties and block-level content
• Create — add new pages to workspaces or data sources, create new data sources
• Update — modify page properties, append blocks, change status fields
• Query — filter and sort data source entries with structured queries
• Design — apply Notion-native visual patterns (mentions, callouts, icons)

Setup

Before using the Notion skill, you need an API integration key and the correct permissions.

# Store your API key
mkdir -p ~/.config/notion
echo "ntn_your_api_key_here" > ~/.config/notion/api_key
chmod 600 ~/.config/notion/api_key

API Helper Function

The skill defines a reusable shell helper that all operations are built on. CLI-JAW uses this internally when executing Notion commands:

NOTION_KEY=$(cat ~/.config/notion/api_key)

# Helper function used by all API calls
notion_api() {
  local method=$1 endpoint=$2 data=$3
  curl -s -X "$method" "https://api.notion.com/v1$endpoint" \
    -H "Authorization: Bearer $NOTION_KEY" \
    -H "Notion-Version: 2025-09-03" \
    -H "Content-Type: application/json" \
    ${data:+-d "$data"}
}

Common Operations

Search

Find pages and data sources by title. Returns matching objects with their IDs.

# Search for pages by title
notion_api POST /search '{"query": "page title"}'

# Discover workspace page IDs
notion_api POST /search '{"query": "Meeting Notes"}'

Read Pages and Blocks

Retrieve page properties and their block-level content.

# Get page properties
notion_api GET /pages/{page_id}

# Get page content (all child blocks)
notion_api GET /blocks/{page_id}/children

Create Pages

Create a new page inside a data source (database) with properties, or as a child of an existing page.

# Create a page in a data source
notion_api POST /pages '{
  "parent": {"database_id": "xxx"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Item"}}]},
    "Status": {"select": {"name": "Todo"}}
  }
}'

Update Pages

Modify page properties without affecting the page content (blocks).

# Update a status property
notion_api PATCH /pages/{page_id} \
  '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Append Blocks

Add new content blocks to an existing page.

# Add a paragraph block
notion_api PATCH /blocks/{page_id}/children '{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"text": {"content": "Hello, world!"}}]
      }
    }
  ]
}'

Query Data Sources

Filter and sort database entries with structured queries.

# Query with filter and sort
notion_api POST /data_sources/{data_source_id}/query '{
  "filter": {
    "property": "Status",
    "select": {"equals": "Active"}
  },
  "sorts": [
    {"property": "Date", "direction": "descending"}
  ]
}'

Create Data Sources

Create a new database (data source) with a defined schema.

# Create a new data source with properties
notion_api POST /data_sources '{
  "parent": {"page_id": "xxx"},
  "title": [{"text": {"content": "My Database"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
    "Date": {"date": {}}
  }
}'

Property Types Reference

Each property type has a specific JSON structure. Use the correct format when creating or updating page properties.

{"title": [{"text": {"content": "..."}}]}

{"rich_text": [{"text": {"content": "..."}}]}

{"select": {"name": "Option"}}

{"multi_select": [{"name": "A"}, {"name": "B"}]}

{"date": {"start": "2024-01-15", "end": "2024-01-16"}}

{"checkbox": true}

{"number": 42}

{"url": "https://..."}

{"email": "user@example.com"}

{"relation": [{"id": "page_id"}]}

2025-09-03 API Changes

The latest Notion API version introduces significant changes to how databases are handled. The skill is built on this version.

Visual Design Rules

The skill includes a set of visual design rules (referred to as the "aesthetics guide") that ensure Notion pages created by CLI-JAW look polished and follow Notion-native patterns.

// Correct: mention link (creates backlink, shows icon)
{"type": "mention", "mention": {"type": "page", "page": {"id": "page-UUID"}}}

// Incorrect: plain text (no backlink, no icon)
{"type": "text", "text": {"content": "Page Name"}}

{"object": "block", "type": "callout", "callout": {
    "rich_text": [
        {"type": "mention", "mention": {"type": "page", "page": {"id": "dashboard-UUID"}}},
        {"type": "text", "text": {"content": " · "}},
        {"type": "mention", "mention": {"type": "page", "page": {"id": "operations-UUID"}}}
    ],
    "icon": {"type": "emoji", "emoji": "🏠"},
    "color": "gray_background"
}}

# Python: safely clear blocks without archiving subpages
for block in children:
    if block["type"] != "child_page":
        delete_block(block["id"])

Environment and Configuration

To discover workspace page IDs for use in scripts and commands:

# Search by name to find page/database UUIDs
notion_api POST /search '{"query": "page name"}'

Usage Examples (~해줌)

Real-world usage patterns in the natural Korean style that CLI-JAW understands.

Important Notes

• Page/database IDs are UUIDs — dashes are optional (abc123def456 and abc123-def4-56... both work)
• Database view filters are UI-only and cannot be set or read via the API
• Inline data sources: use is_inline: true when creating a data source to embed it inside a page rather than as a standalone full-page database
• child_page safety: never delete child_page blocks when clearing content — this permanently archives the subpage
• Dual ID system: in the 2025-09-03 API, databases have both database_id (for page creation) and data_source_id (for queries) — use the correct one for each operation
• Rate limiting: the Notion API allows ~3 requests/sec; insert time.sleep(0.35) between calls in batch scripts
• Integration access: every page and database you want to access must be explicitly shared with the integration in Notion's share dialog

Related

• Notion API Documentation — official Notion API reference
• Productivity Skills — category page for Notion and related productivity skills
• Memory — persistent knowledge storage across sessions
• Skill Catalog — browse all skills
• CLI Commands — full CLI-JAW command reference