Notion API Client (Unofficial)

Warnings

• breaking This library relies on Notion's unofficial/internal API, which is subject to change without notice. The v0.1.0 release (March 2026) introduced breaking changes to adapt to Notion's latest internal API (v3) modifications, including migration from `getRecordValues` to `syncRecordValues`, updated `queryCollection` aggregation, `getBacklinksForBlock` to `getBacklinksForBlockInitial`, and `search` endpoint sort parameter format.
  Fix: Upgrade to version 0.1.0 or newer and review the release notes for necessary code adjustments, as endpoint names and data formats may have changed.
• gotcha Authentication uses `token_v2`, obtained from Notion.so browser cookies. This token is session-specific, highly fragile, and prone to expiration or invalidation without warning, leading to `HTTPError` or `Unauthorized` errors.
  Fix: Regularly verify your `token_v2` and re-obtain it from your browser cookies if authentication fails. For a more stable and official integration, consider using the `notion-sdk-py` library with an official Notion integration token.
• gotcha There is significant confusion between this unofficial `notion` library (`jamalex/notion-py` on GitHub) and the official Python SDK, `notion-sdk-py`. The two libraries are not fully compatible and use different authentication methods and API patterns.
  Fix: Be explicit about which library you intend to use. If targeting the official Notion API, use `pip install notion-client` and import `from notion_client import Client`. If you specifically need the features or internal API access of `jamalex/notion-py`, proceed with caution, understanding its unofficial nature.
• gotcha When using `client.get_block()`, ensure the `token_v2` has explicit read/write permissions to the specific Notion page or database you are trying to access. Lack of permissions often results in `object_not_found` or `restricted_resource` errors, even with a valid token.
  Fix: In Notion, share the target page/database with the 'integration' associated with your `token_v2`. Ensure the page is not in a private or restricted state.

Install

• pip install notion Install stable version

Imports

• NotionClient

  from notion.client import NotionClient

  This is the primary client class for interacting with Notion.

Quickstart

Initializes the NotionClient using a `token_v2` (obtained from browser cookies, not an official integration token) and retrieves a Notion page. This example demonstrates basic page access and highlights the authentication method.

import os
from notion.client import NotionClient

# IMPORTANT: This library uses the internal Notion API and requires a token_v2 from browser cookies.
# It is unofficial and prone to breakage. For official API access, use 'notion-sdk-py'.
# Replace 'NOTION_TOKEN_V2' with your actual token_v2 from Notion.so browser cookies.
# This token is session-specific and can expire.
token_v2 = os.environ.get('NOTION_TOKEN_V2', '')

if not token_v2:
    print("Error: NOTION_TOKEN_V2 environment variable not set. Please provide your token_v2 cookie value.")
else:
    try:
        client = NotionClient(token_v2=token_v2)
        # Replace with the URL or ID of a Notion page you have access to
        page_url = "https://www.notion.so/myorg/Test-c0d20a71c0944985ae96e661ccc99821" # Example URL
        
        # Ensure the client's token has access to the page
        page = client.get_block(page_url)
        print(f"Successfully accessed page: {page.title}")
        
        # Example: Update the page title
        # page.title = "New Title from Python!"
        # print(f"Page title updated to: {page.title}")

        # Example: List children blocks (if any)
        # for child in page.children:
        #     print(f"  - Child block: {child.title}")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Common issues: invalid token_v2, page not shared with the token's user, or Notion's internal API changed.")