notion-api

Notion REST API — Direct wrapper for batch operations

When working with Notion programmatically, use the REST API (not the MCP) for any batch-shaped work. MCP implementations (like notion-search) typically have hard limitations (25-result caps, no real pagination) that make batch operations tedious. The REST API handles 100+ rows in seconds with auto-pagination.

---

When to use REST API vs MCP

Operation	Use
Read 1 page, update 1 page, search for a page	MCP OK
Add a comment, create a single inline note	MCP OK
Query an entire database (any size), with filters and pagination	REST API
Batch update N pages (rename, retag, restructure)	REST API
Audit/scan/inventory a database	REST API
Replicate page body blocks	REST API
Upload files/images programmatically	REST API (MCP cannot)
Create a new database programmatically	REST API
Move pages by re-creating under a new parent	REST API
Any operation touching ≥3 rows	REST API

If you find yourself calling MCP twice for the same data, switch to the REST API.

---

Python wrapper pattern

Create a thin self-contained wrapper around the Notion REST API. This wrapper should:

• Handle authentication via environment variable (e.g., NOTION_API_KEY or NOTION_TOKEN)
• Provide auto-pagination for list endpoints (use start_cursor / has_more loops)
• Include retry logic with exponential backoff for rate limits (HTTP 429) and transient errors (5xx)
• Throttle writes to respect Notion's published rate limit (~3 req/s)
• Expose CRUD functions for pages, databases, blocks, and comments
• Include property builders for clean schema construction (title, rich_text, select, date, etc.)
• Avoid external dependencies — use Python stdlib only (e.g., urllib, json, time)

Canonical imports (your wrapper should export)

# Core CRUD
get_page, create_page, update_page, archive_page
get_database, create_database, update_database

# Querying (query_db_all should auto-paginate)
query_database, query_db_all

# Blocks
get_block, list_block_children, list_block_children_all
append_block_children, update_block, delete_block

# Search and metadata
search, search_all, list_users_all, get_user, whoami
create_comment, list_comments_all

# File uploads (for image/attachment re-hosting)
file_upload_create, file_upload_send, file_upload_complete

# Property builders (clean payloads)
title_prop, rich_text_prop, select_prop, multi_select_prop
status_prop, number_prop, checkbox_prop, date_prop, url_prop
relation_prop, people_prop, files_prop

# Block builders
paragraph_block, heading_block, bulleted_list_item, numbered_list_item
to_do_block, code_block, divider_block, callout_block, quote_block

# Text helpers
title_text, rich_text_text

# Custom exceptions
NotionAPIError