The Modern Notion API for Python & AI Agents

Transform complex Notion API interactions into simple, Pythonic code. Perfect for developers building AI agents, automation workflows, and dynamic content systems.

---

Why Notionary?

• AI-Native Design - Built specifically for AI agents with schema-driven markdown syntax
• Smart Discovery - Find pages and databases by name with fuzzy matching—no more hunting for IDs
• Extended Markdown - Rich syntax for toggles, columns, callouts, and media uploads
• Async-First - Modern Python with full async/await support and high performance
• Round-Trip - Read existing content, modify it, and write it back while preserving formatting
• Complete Coverage - Every Notion block type supported with type safety

---

Installation

pip install notionary

Set up your Notion integration and configure your token:

export NOTION_SECRET=your_integration_key

---

See It in Action

create_page_in_database_demo.mp4

Create rich database entries with properties, content, and beautiful formatting

---

Quick Start

Find → Create → Update Flow

from notionary import NotionPage

# Find pages by name with fuzzy matching
page = await NotionPage.from_title("Meeting Notes")

# Define rich content with extended markdown
content = """
## Action Items
- [x] Review proposal
- [ ] Schedule meeting

[callout](Key decision made! "💡")

| Task | Owner | Deadline |
|------|-------|----------|
| Design Review | Alice | 2024-03-15 |
| Implementation | Bob | 2024-03-22 |

+++ Budget Details
See attached spreadsheet...
+++
"""

await page.append_markdown(content)

Complete Block Support

Every Notion block type with extended syntax:

Block Type	Markdown Syntax	Use Case
Toggles	+++ Title\nContent\n+++	Collapsible sections
Columns	::: columns\n::: column\nContent\n:::\n:::	Side-by-side layouts
Tables	Standard markdown tables	Structured data
Media	[video](./file.mp4)(caption:Description)	Auto-uploading files
Code	Standard code fences with captions	Code snippets
Equations	$LaTeX$	Mathematical expressions
TOC	[toc]	Auto-generated navigation

---

Key Features

Smart Discovery Find pages/databases by name Fuzzy matching for approximate searches No more hunting for IDs or URLs Extended Markdown Rich syntax beyond standard markdown Callouts, toggles, columns, media uploads Schema provided for AI agent integration Modern Python Full async/await support Type hints throughout High-performance batch operations

Round-Trip Editing Read existing content as markdown Edit and modify preserving formatting Write back to Notion seamlessly AI-Ready Architecture Schema-driven syntax for LLM prompts Perfect for AI content generation Handles complex nested structures Complete Coverage Every Notion block type supported File uploads with automatic handling Database operations and properties

---

Examples & Documentation

Full Documentation

mathisarends.github.io/notionary - Complete API reference, guides, and tutorials

---

Contributing

We welcome contributions from the community! Whether you're:

• Fixing bugs - Help improve stability and reliability
• Adding features - Extend functionality for new use cases
• Improving docs - Make the library more accessible
• Sharing examples - Show creative applications and patterns

Check our Contributing Guide to get started.

---

Ready to revolutionize your Notion workflows?

📖 Read the Docs • 🚀 Getting Started • 💻 Browse Examples

Built with ❤️ for Python developers and AI agents

---

Transform complex Notion API interactions into simple, powerful code.