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

markdown
11. Go to https://www.notion.so/my-integrations
22. Click "New integration"
33. Name: "My Integration"
44. Select workspace
55. Set capabilities (Read/Write content, etc.)
66. Copy the "Internal Integration Token"

Connect Integration to Pages

markdown
11. Open the Notion page/database you want to access
22. Click "..." menu (top right)
33. Click "Connections" > "Connect to" > Your integration
44. Integration can now access this page and children

Environment Setup

bash
1# Set environment variable
2export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxx"
3
4# Verify connection
5curl -s "https://api.notion.com/v1/users/me" \
6    -H "Authorization: Bearer $NOTION_API_KEY" \
7    -H "Notion-Version: 2022-06-28" | jq

Python SDK Installation

bash
1# Install official Python client
2pip install notion-client
3
4# Or with uv
5uv pip install notion-client
6
7# Additional dependencies
8pip install python-dotenv requests

Verify Setup

python
1from notion_client import Client
2import os
3
4notion = Client(auth=os.environ["NOTION_API_KEY"])
5
6# Test connection
7me = notion.users.me()
8print(f"Connected as: {me['name']}")
9
10# List accessible databases
11databases = notion.search(filter={"property": "object", "value": "database"})
12print(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)