Transform complex Notion API interactions into simple, Pythonic code. Perfect for developers building AI agents, automation workflows, and dynamic content systems.
- 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
pip install notionarySet up your Notion integration and configure your token:
export NOTION_SECRET=your_integration_keycreate_page_in_database_demo.mp4
Create rich database entries with properties, content, and beautiful formatting
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)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 |
|
|
mathisarends.github.io/notionary - Complete API reference, guides, and tutorials
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.