Notion Upgrade & Migration

Overview

Step-by-step guide for upgrading @notionhq/client (Node.js) and notion-client (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version 2022-06-28 and the SDK feature timeline through v2.x.

Prerequisites

• Existing project with @notionhq/client or notion-client installed
• Git repository with clean working tree (no uncommitted changes)
• Test suite covering Notion API calls (or willingness to add verification tests)
• NOTION_TOKEN environment variable configured

Instructions

Step 1: Audit Current Versions and API Surface

Determine what you are running today before changing anything.