Transform complex Notion API interactions into simple, Pythonic code. Perfect for developers building AI agents, automation workflows, and dynamic content systems.
- AI-friendly – Composable APIs that drop cleanly into agent workflows
- Smart discovery – Find pages/databases by title with fuzzy matching (no ID spelunking)
- Extended Markdown – Toggles, columns, callouts, media, equations, tables, TOC
- Async-first – Modern Python with full
async/await - Round‑trip content – Read a page as Markdown, transform, write back
- Full coverage – All Notion block types with sensible defaults and 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)Read or replace content:
existing = await page.get_markdown_content() print(existing) await page.replace_content("# Fresh Start\nThis page was rewritten.")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](https://example.com/file.mp4) | External media URLs |
| Code | Standard code fences with captions | Code snippets |
| Equations | $LaTeX$ | Mathematical expressions |
| TOC | [toc] | Auto-generated navigation |
flowchart TD WS[Workspace] --> DB[(Database)] WS --> PG[Page] DB --> DS[(Data Source)] DS --> PG WS --> USR[Users] PG --> BLK[Blocks] PG --> CM[Comments] PG --> PROP[Properties]
|
|
from notionary import MarkdownBuilder markdown = ( MarkdownBuilder() .h2("Setup Guide") .paragraph("Basic steps.") .toggle("Advanced Options", lambda b: b.paragraph("Power user settings.") .bulleted_list(["Debug mode", "Custom timeouts"])) .columns( lambda c: c.paragraph("Left column"), lambda c: c.paragraph("Right column") ) .build() ) page = await NotionPage.from_title("Playground") await page.append_markdown(markdown)from notionary import NotionWorkspace, NotionWorkspaceQueryConfigBuilder workspace = await NotionWorkspace.from_current_integration() builder = NotionWorkspaceQueryConfigBuilder() config = ( builder .with_pages_only() .with_query("roadmap") .with_page_size(5) .build() ) pages = await workspace.get_pages(config) for p in pages: print(p.title)from notionary import NotionDataSource ds = await NotionDataSource.from_title("Engineering Backlog") status_labels = ds.get_status_options_by_property_name("Status") print(status_labels) builder = ds.get_query_builder() params = ( builder .where("Status") .equals("In Progress") .order_by_last_edited_time() .build() ) pages = await ds.get_pages(query_params=params)page = await NotionPage.from_title("Sprint Board") await page.properties.set_select_property_by_option_name("Phase", "Design") await page.properties.set_multi_select_property_by_option_names("Tags", ["Backend", "API"]) await page.properties.set_status_property_by_option_name("Status", "In Progress")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.