{"id":4131,"library":"notion","title":"Notion API Client (Unofficial)","description":"This is an unofficial Python API client for Notion.so, providing an object-oriented interface to interact with Notion data. It's currently at version 0.1.0 (released March 2026) and aims to adapt to Notion's internal API changes. As an unofficial client, its release cadence is driven by necessary adaptations to Notion's evolving undocumented API.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://github.com/jamalex/notion-py","tags":["notion","api-client","unofficial","productivity"],"install":[{"cmd":"pip install notion","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This is the primary client class for interacting with Notion.","symbol":"NotionClient","correct":"from notion.client import NotionClient"}],"quickstart":{"code":"import os\nfrom notion.client import NotionClient\n\n# IMPORTANT: This library uses the internal Notion API and requires a token_v2 from browser cookies.\n# It is unofficial and prone to breakage. For official API access, use 'notion-sdk-py'.\n# Replace 'NOTION_TOKEN_V2' with your actual token_v2 from Notion.so browser cookies.\n# This token is session-specific and can expire.\ntoken_v2 = os.environ.get('NOTION_TOKEN_V2', '')\n\nif not token_v2:\n    print(\"Error: NOTION_TOKEN_V2 environment variable not set. Please provide your token_v2 cookie value.\")\nelse:\n    try:\n        client = NotionClient(token_v2=token_v2)\n        # Replace with the URL or ID of a Notion page you have access to\n        page_url = \"https://www.notion.so/myorg/Test-c0d20a71c0944985ae96e661ccc99821\" # Example URL\n        \n        # Ensure the client's token has access to the page\n        page = client.get_block(page_url)\n        print(f\"Successfully accessed page: {page.title}\")\n        \n        # Example: Update the page title\n        # page.title = \"New Title from Python!\"\n        # print(f\"Page title updated to: {page.title}\")\n\n        # Example: List children blocks (if any)\n        # for child in page.children:\n        #     print(f\"  - Child block: {child.title}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Common issues: invalid token_v2, page not shared with the token's user, or Notion's internal API changed.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions prior to 0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}