Skip to content

notion-py-client

Install using pip:

pip install notion-py-client

Quick Example

Overview

notion-py-client provides a complete type system mirroring Notion's TypeScript API definitions. It offers full coverage of Databases, Data Sources, Pages, Blocks (35 types), Filters, and Request types with strict runtime validation.

Key Features

  • Type Safety: Built on Pydantic v2 with strict type validation
  • Complete API Coverage: Latest Notion API 2026-03-11 compatibility
  • TypeScript Compatibility: Mirrors official TypeScript type definitions
  • Async First: Built with httpx for async HTTP operations
  • Developer Friendly: Intuitive API design with comprehensive type hints

Installation

Install using pip:

pip install notion-py-client

Quick Example

from notion_py_client import NotionAsyncClient

async with NotionAsyncClient(auth="secret_xxx") as client:
    # Query a data source (2026-03-11 API)
    response = await client.dataSources.query(
        data_source_id="ds_abc123",
        filter={
            "property": "Status",
            "select": {"equals": "Done"}
        }
    )

    for page in response.results:
        print(f"Page: {page.id}")

API Version

This library supports Notion API version 2026-03-11, including:

  • Current breaking changes: position, in_trash, and meeting_notes
  • Markdown page APIs: create, retrieve, and update page markdown
  • Comments API: create/update comments with rich text or inline markdown
  • Meeting notes: query AI meeting notes blocks
  • Custom emoji listing: workspace custom emoji pagination
  • Result status: exposes request_status for incomplete paginated results
  • Data source model: continued support for the 2025-09-03 split

Next Steps