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

Creating Rich Database Entries

create_page_in_database_demo.mp4

Create styled project pages with properties, content, and rich formatting

Local File Uploads (Videos & Images)

upload_local_files.mp4

Upload videos and images using simple markdown syntax - files are automatically uploaded to Notion

---

Quick Start

Find → Create → Update Flow

import asyncio
from notionary import NotionPage, NotionDatabase

async def main():
    # Find pages by name - fuzzy matching included!
    page = await NotionPage.from_title("Meeting Notes")

    # Option 1: Direct Extended Markdown
    await page.append_markdown("""
    ## Action Items
    - [x] Review project proposal
    - [ ] Schedule team meeting
    - [ ] Update documentation

    [callout](Meeting decisions require follow-up "💡")

    +++ Details
    Additional context and next steps...
    +++
    """)

    # Option 2: Type-Safe Builder (maps to same markdown internally)
    await page.append_markdown(lambda builder: (
        builder
        .h2("Project Status")
        .callout("Milestone reached!", "🎉")
        .columns(
            lambda col: col.h3("Completed").bulleted_list([
                "API design", "Database setup", "Authentication"
            ]),
            lambda col: col.h3("In Progress").bulleted_list([
                "Frontend UI", "Testing", "Documentation"
            ]),
            width_ratios=[0.6, 0.4]
        )
        .toggle("Budget Details", lambda t: t
            .table(["Item", "Cost", "Status"], [
                ["Development", "$15,000", "Paid"],
                ["Design", "$8,000", "Pending"]
            ])
        )
    ))

asyncio.run(main())

Complete Block Support

Every Notion block type with extended syntax:

Block Type	Markdown Syntax	Use Case
Callouts	[callout](Text "🔥")	Highlighting key information
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](blue_background)	Auto-generated navigation

---

What You Can Build 💡

AI Content Systems

• Report Generation: AI agents that create structured reports, documentation, and analysis
• Content Pipelines: Automated workflows that process data and generate Notion pages
• Knowledge Management: AI-powered documentation systems with smart categorization

Workflow Automation

• Project Management: Sync project status, update timelines, generate progress reports
• Data Integration: Connect external APIs and databases to Notion workspaces
• Template Systems: Dynamic page generation from templates and data sources

Content Management

• Bulk Operations: Mass page updates, content migration, and database management
• Media Handling: Automated image/video uploads with proper organization
• Cross-Platform: Sync content between Notion and other platforms

---

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

Quick Links

• Getting Started - Setup and first steps
• Page Management - Content and properties
• Database Operations - Queries and management
• Block Types Reference - Complete syntax guide

Hands-On Examples

Core Functionality:

• Page Management - Create, update, and manage pages
• Database Operations - Connect and query databases
• Workspace Discovery - Explore your workspace

Extended Markdown:

• Basic Formatting - Text, lists, and links
• Callouts & Highlights - Information boxes
• Toggle Sections - Collapsible content
• Multi-Column Layouts - Side-by-side design
• Tables & Data - Structured presentations

---

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.