Notion API

Notion Api

When to Use This Skill

USE Notion API when:

• Automating database entries and updates
• Building custom dashboards from Notion data
• Syncing data between Notion and external systems
• Creating pages programmatically from templates
• Querying databases with complex filters
• Building integrations with other productivity tools
• Generating reports from Notion databases
• Implementing workflow automations

DON'T USE Notion API when:

• Need real-time sync (API has rate limits)
• Building chat/messaging features (use Slack API)
• Need file storage solution (use dedicated storage)
• Simple task management only (use Todoist API)
• Need offline-first solution (use Obsidian)
• Require sub-second response times

Prerequisites

Create Integration

1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Name: "My Integration"
4. Select workspace
5. Set capabilities (Read/Write content, etc.)
6. Copy the "Internal Integration Token"

Connect Integration to Pages

1. Open the Notion page/database you want to access
2. Click "..." menu (top right)
3. Click "Connections" > "Connect to" > Your integration
4. Integration can now access this page and children

Environment Setup

# Set environment variable
export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxx"

# Verify connection
curl -s "https://api.notion.com/v1/users/me" \
    -H "Authorization: Bearer $NOTION_API_KEY" \
    -H "Notion-Version: 2022-06-28" | jq

Python SDK Installation

# Install official Python client
pip install notion-client

# Or with uv
uv pip install notion-client

# Additional dependencies
pip install python-dotenv requests

Verify Setup

from notion_client import Client
import os

notion = Client(auth=os.environ["NOTION_API_KEY"])

# Test connection
me = notion.users.me()
print(f"Connected as: {me['name']}")

# List accessible databases
databases = notion.search(filter={"property": "object", "value": "database"})
print(f"Found {len(databases['results'])} databases")

Version History

Resources

• Notion API Documentation
• API Reference
• Python SDK
• JavaScript SDK
• Integration Gallery
• API Changelog

This skill enables powerful workspace automation through Notion's comprehensive API, supporting databases, pages, blocks, queries, and integration patterns.

Sub-Skills

• 1. Database Operations
• 2. Query Databases
• 3. Filter Syntax Reference
• 4. Page Operations
• 5. Block Operations
• 6. Rich Text Formatting (+1)
• 8. Search API
• Integration with Slack (+1)
• 1. Rate Limiting (+3)
• Common Issues

Sub-Skills

• Example 1: Task Management System (+2)