Notion API

Notion API Integration

Access Notion pages, databases, and content through TypeScript scripts executed via Bun.

Overview

This skill provides access to the Notion API for:

• Search: Find pages and databases across your workspace
• Pages: Get, create, and update pages
• Databases: Query database entries with filters and sorting
• Blocks: Read page content as blocks

All scripts return JSON and require a NOTION_TOKEN environment variable.

Response Format

All scripts output JSON with a consistent structure:

Success

{"status": "success", "data": {...}}

Authentication Required

{
  "status": "auth_required",
  "message": "Set NOTION_TOKEN environment variable with your integration token...",
  "setupUrl": "https://www.notion.so/my-integrations"
}

When you receive auth_required, display to the user:

To access Notion, you need to set up an integration:
1. Go to: https://www.notion.so/my-integrations
2. Create a new integration for your workspace
3. Copy the "Internal Integration Secret"
4. Set the NOTION_TOKEN environment variable with this token
5. Share your pages/databases with the integration (click "..." menu > "Add connections")

Let me know when you've completed setup.

Error

{"status": "error", "error": "Error description"}

Search

Search for pages and databases across your Notion workspace.

All scripts are located at ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/.

# Search for pages/databases matching a query
bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/search.ts --query "meeting notes"

# Search only pages
bun run search.ts --query "project" --filter page

# Search only databases
bun run search.ts --filter database --top 20

# List all accessible items (no query)
bun run search.ts --top 10

Pages

Get, create, and update Notion pages.

Get Page

bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/pages.ts get --id <page-id>

Create Page

# Create as child of another page
bun run pages.ts create --parent-id <page-id> --title "New Page"

# Create as child of another page with icon
bun run pages.ts create --parent-id <page-id> --title "New Page" --icon "📝"

# Create as database entry
bun run pages.ts create --parent-id <database-id> --parent-type database --title "New Entry"

# Create database entry with properties
bun run pages.ts create --parent-id <db-id> --parent-type database --title "Task" \
  --properties '{"Status": {"select": {"name": "To Do"}}, "Priority": {"select": {"name": "High"}}}'

Update Page

# Update title
bun run pages.ts update --id <page-id> --title "Updated Title"

# Update icon
bun run pages.ts update --id <page-id> --icon "🎉"

# Archive page
bun run pages.ts update --id <page-id> --archived true

# Restore archived page
bun run pages.ts update --id <page-id> --archived false

# Update database page properties
bun run pages.ts update --id <page-id> --properties '{"Status": {"select": {"name": "Done"}}}'

Databases

Query and get information about Notion databases.

Get Database Schema

bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/databases.ts get --id <database-id>

Returns the database title, description, and all property definitions.

Query Database

# Query all entries
bun run databases.ts query --id <database-id>

# Query with limit
bun run databases.ts query --id <db-id> --top 20

# Query with filter
bun run databases.ts query --id <db-id> --filter '{"property": "Status", "select": {"equals": "Done"}}'

# Query with multiple conditions (AND)
bun run databases.ts query --id <db-id> --filter '{"and": [
  {"property": "Status", "select": {"equals": "In Progress"}},
  {"property": "Priority", "select": {"equals": "High"}}
]}'

# Query with sorting
bun run databases.ts query --id <db-id> --sorts '[{"property": "Created", "direction": "descending"}]'

# Sort by last edited time
bun run databases.ts query --id <db-id> --sorts '[{"timestamp": "last_edited_time", "direction": "descending"}]'

Common Filter Examples

# Text contains
--filter '{"property": "Name", "rich_text": {"contains": "project"}}'

# Checkbox is checked
--filter '{"property": "Done", "checkbox": {"equals": true}}'

# Date is after
--filter '{"property": "Due Date", "date": {"after": "2024-01-01"}}'

# Number greater than
--filter '{"property": "Score", "number": {"greater_than": 80}}'

# OR conditions
--filter '{"or": [
  {"property": "Status", "select": {"equals": "Done"}},
  {"property": "Status", "select": {"equals": "Archived"}}
]}'

Blocks (Page Content)

Read page content as blocks.

List Page Blocks

# Get blocks from a page
bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/blocks.ts list --id <page-id>

# Get blocks with limit
bun run blocks.ts list --id <page-id> --top 100

# Get blocks recursively (includes nested content)
bun run blocks.ts list --id <page-id> --recursive

Get Specific Block

bun run blocks.ts get --id <block-id>

Block Types

Blocks can be: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, toggle, code, quote, callout, divider, table, image, bookmark, and more.

Each block includes:

• id: Block identifier
• type: Block type
• content: Text content (if applicable)
• hasChildren: Whether block has nested blocks
• children: Nested blocks (when using --recursive)

Authentication Setup

1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Give it a name and select the workspace
4. Copy the "Internal Integration Secret"
5. Set the environment variable:

   export NOTION_TOKEN=secret_xxxxx
   

6. Share pages/databases with the integration:
   • Open the page or database in Notion
   • Click the "..." menu in the top right
   • Select "Add connections"
   • Find and select your integration

Important Notes

• Sharing required: Pages and databases must be shared with your integration before they can be accessed
• Rate limits: Notion API allows ~3 requests per second on average
• Page IDs: Can be found in the page URL (the 32-character string after the page name)
• Database IDs: Same format as page IDs, found in the database URL

Script Reference

Additional Resources

For detailed API reference, see:

• references/notion-api.md - Notion API endpoints and parameters