Notion Workspace

Notion Workspace Skill

Overview

This skill provides access to Notion API operations using progressive disclosure for optimal context usage.

Context Savings: ~90% reduction

• Direct API Mode: Loading all API documentation and examples
• Skill Mode: ~300 tokens metadata + on-demand tool loading

Requirements

• NOTION_API_KEY environment variable set (Notion integration token)
• NOTION_VERSION optional (default: 2022-06-28)

Toolsets

The skill provides tools across 5 categories:

Quick Reference

# Get page content
python executor.py --tool get-page --args '{"page_id": "abc123"}'

# Create page
python executor.py --tool create-page --args '{"parent": {"page_id": "parent123"}, "properties": {"title": [{"text": {"content": "New Page"}}]}}'

# Query database
python executor.py --tool query-database --args '{"database_id": "db123", "filter": {}}'

# Search workspace
python executor.py --tool search --args '{"query": "meeting notes", "filter": {"property": "object", "value": "page"}}'

# List users
python executor.py --tool list-users --args '{}'

Common Tools (Default Toolsets)

Pages

get-page:

python executor.py --tool get-page --args '{"page_id": "abc123def456"}'

create-page:

python executor.py --tool create-page --args '{
  "parent": {"page_id": "parent_page_id"},
  "properties": {
    "title": [{"text": {"content": "Project Plan"}}]
  }
}'

update-page:

python executor.py --tool update-page --args '{
  "page_id": "abc123",
  "properties": {
    "Status": {"select": {"name": "In Progress"}}
  }
}'

archive-page:

python executor.py --tool archive-page --args '{"page_id": "abc123", "archived": true}'

Databases

query-database:

python executor.py --tool query-database --args '{
  "database_id": "db123",
  "filter": {
    "property": "Status",
    "select": {"equals": "Done"}
  },
  "sorts": [{"property": "Created", "direction": "descending"}]
}'

add-row:

python executor.py --tool add-row --args '{
  "database_id": "db123",
  "properties": {
    "Name": {"title": [{"text": {"content": "New Task"}}]},
    "Status": {"select": {"name": "To Do"}},
    "Priority": {"select": {"name": "High"}}
  }
}'

create-database:

python executor.py --tool create-database --args '{
  "parent": {"page_id": "parent123"},
  "title": [{"text": {"content": "Project Tracker"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "To Do"}, {"name": "Done"}]}},
    "Due": {"date": {}}
  }
}'

Blocks

get-children:

python executor.py --tool get-children --args '{"block_id": "page_or_block_id"}'

append-blocks:

python executor.py --tool append-blocks --args '{
  "block_id": "page123",
  "children": [
    {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "New paragraph"}}]}},
    {"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Section Title"}}]}}
  ]
}'

Search

search:

python executor.py --tool search --args '{
  "query": "project plan",
  "filter": {"property": "object", "value": "page"},
  "sort": {"direction": "descending", "timestamp": "last_edited_time"}
}'

Users

list-users:

python executor.py --tool list-users --args '{}'

get-user:

python executor.py --tool get-user --args '{"user_id": "user123"}'

Configuration

Environment Variables

Getting a Notion API Key

1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Configure integration name and workspace
4. Copy the "Internal Integration Token"
5. Share pages/databases with your integration

Limiting Toolsets

To reduce context and improve tool selection, enable only needed toolsets:

# Only pages and search
NOTION_TOOLSETS=pages,search python executor.py --list

# Only databases
NOTION_TOOLSETS=databases python executor.py --list

Agent Integration

Primary Agents:

• pm - Project management, task tracking
• technical-writer - Documentation management

Secondary Agents:

• analyst - Research, note-taking
• developer - Technical documentation
• orchestrator - Workflow coordination

Security

API Key Protection:

• Never expose NOTION_API_KEY in logs or output
• Store API key securely using environment variables
• Use integration-level permissions to limit access

Confirmation Required:

• All page mutations (create, update, archive)
• All database mutations (create, add rows, update)
• All block mutations (append, update, delete)

Read-Only Mode: Set NOTION_READ_ONLY=1 to disable all mutation operations:

NOTION_READ_ONLY=1 python executor.py --tool create-page --args '{...}'
# Error: Operation not allowed in read-only mode

Common Patterns

Project Management

# Create project database
python executor.py --tool create-database --args '{
  "parent": {"page_id": "workspace_page"},
  "title": [{"text": {"content": "Projects"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "Planning"}, {"name": "Active"}, {"name": "Done"}]}},
    "Owner": {"people": {}},
    "Due Date": {"date": {}}
  }
}'

# Add project
python executor.py --tool add-row --args '{
  "database_id": "projects_db",
  "properties": {
    "Name": {"title": [{"text": {"content": "Q1 Launch"}}]},
    "Status": {"select": {"name": "Planning"}},
    "Due Date": {"date": {"start": "2025-03-31"}}
  }
}'

# Query active projects
python executor.py --tool query-database --args '{
  "database_id": "projects_db",
  "filter": {"property": "Status", "select": {"equals": "Active"}}
}'

Documentation

# Create documentation page
python executor.py --tool create-page --args '{
  "parent": {"page_id": "docs_parent"},
  "properties": {"title": [{"text": {"content": "API Reference"}}]}
}'

# Add content blocks
python executor.py --tool append-blocks --args '{
  "block_id": "api_ref_page",
  "children": [
    {"object": "block", "type": "heading_1", "heading_1": {"rich_text": [{"text": {"content": "API Reference"}}]}},
    {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "This document describes the API endpoints."}}]}},
    {"object": "block", "type": "code", "code": {"language": "javascript", "rich_text": [{"text": {"content": "fetch('/api/users')"}}]}}
  ]
}'

Meeting Notes

# Create meeting notes page
python executor.py --tool create-page --args '{
  "parent": {"database_id": "meetings_db"},
  "properties": {
    "Name": {"title": [{"text": {"content": "Team Sync - 2025-01-05"}}]},
    "Date": {"date": {"start": "2025-01-05"}},
    "Attendees": {"people": [{"id": "user1"}, {"id": "user2"}]}
  }
}'

# Search for meeting notes
python executor.py --tool search --args '{
  "query": "Team Sync",
  "filter": {"property": "object", "value": "page"}
}'

Error Handling

If tool execution fails:

1. Verify NOTION_API_KEY is set and valid
2. Ensure integration has access to the page/database
3. Check API version compatibility (NOTION_VERSION)
4. Review executor.py output for specific error details
5. Verify page/database IDs are correct (32-character hex strings without hyphens)

Common Errors:

• object_not_found: Page/database not shared with integration
• validation_error: Invalid request parameters
• unauthorized: Invalid API key or insufficient permissions
• rate_limited: Too many requests, retry with exponential backoff

Rate Limits

Notion API has rate limits:

• Rate limit: ~3 requests per second
• Burst limit: Up to 10 requests in a short burst
• Best practice: Add delays between batch operations

# Batch operation with delay
for page_id in page_ids; do
  python executor.py --tool get-page --args "{\"page_id\": \"$page_id\"}"
  sleep 0.5  # 500ms delay
done

Related

• Official Notion API Documentation: https://developers.notion.com
• Notion API Reference: https://developers.notion.com/reference
• Integration Setup Guide: https://www.notion.so/help/create-integrations-with-the-notion-api