{"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":"python","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,"search_vec":"'0.1.0':30 '2026':33 'adapt':37,55 'aim':35 'api':2,10,42,61,64 'api-cli':63 'cadenc':50 'chang':43 'client':3,11,47,65 'current':27 'data':24 'driven':52 'evolv':59 'interact':21 'interfac':19 'intern':41 'march':32 'necessari':54 'notion':1,23,39,57,62 'notion.so':13 'object':17 'object-ori':16 'orient':18 'product':67 'provid':14 'python':9 'releas':31,49 'undocu':60 'unoffici':4,8,46,66 'version':29","created_at":"2026-04-12T03:42:17.745225+00:00","updated_at":"2026-04-16T17:24:13.675963+00:00","problems":[{"fix":"Install the library using pip: `pip install notion`","cause":"The 'notion' library has not been installed in your Python environment, or the Python interpreter cannot find the installed package.","error":"ModuleNotFoundError: No module named 'notion'"},{"fix":"Ensure you are using a valid Notion integration token (often starting with `secret_` or `ntn_`). Verify that the integration has been explicitly shared with the page or database in Notion, and double-check that the token is passed correctly when initializing the client.","cause":"The Notion API token provided is invalid, has insufficient permissions, or is incorrectly formatted. This can also happen if your integration has not been granted access to the specific Notion page or database you are trying to interact with.","error":"HTTPError: 401 Client Error: Unauthorized"},{"fix":"Add checks for `None` or empty responses after making Notion API calls. Ensure that the IDs used to fetch Notion objects are correct and accessible by your integration. Wrap API calls in `try-except` blocks to gracefully handle potential `HTTPError`s or unexpected `None` returns.","cause":"An API call to Notion likely returned `None` (e.g., because a resource was not found, or an error occurred during the API request), and your code attempted to access an attribute or method (like `.items()`) on this `None` object without proper error handling.","error":"AttributeError: 'NoneType' object has no attribute 'items'"},{"fix":"Double-check the Notion ID (page, database, or block) for accuracy. Confirm that your Notion integration has been explicitly granted access to the page or database you are trying to interact with by adding it under 'Connections' in Notion.","cause":"The specific Notion page, database, or block ID you are trying to access does not exist, or your integration does not have permission to view that particular resource.","error":"404 Client Error: Not Found"},{"fix":"Implement rate limiting and exponential backoff in your code. When a 429 error is received, pause requests and retry after waiting for the duration specified in the `Retry-After` header of the API response.","cause":"You have exceeded Notion's API rate limits, which are typically around three requests per second for standard integrations.","error":"429 Client Error: Too Many Requests"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://notion.so","github":"https://github.com/jamalex/notion-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/notion/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["crm-productivity","http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}