| name | notion-upgrade-migration |
| description | Upgrade @notionhq/client SDK versions and migrate between Notion API versions.
Use when updating SDK packages, handling breaking changes between API versions,
adopting new SDK features like comments API or status properties, or migrating Python notion-client.
Trigger with phrases like "upgrade notion SDK", "notion migration", "notion breaking changes",
"update notionhq client", "notion API version upgrade", "notion deprecation".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(git:*), Glob, Grep |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
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.
The workflow is three phases — audit what you run today, upgrade on an isolated branch while fixing breaking changes, then verify every API surface before merging. Deep code (the full breaking-change catalog, the verification suite, and worked recipes) lives in references/ so this file stays a scannable playbook.
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.
npm ls @notionhq/client
npm view @notionhq/client version
pip show notion-client 2>/dev/null | grep Version
pip index versions notion-client 2>/dev/null | head -1
grep -rn "notionVersion\|Notion-Version\|notion_version" src/ lib/ app/ 2>/dev/null
Record the current SDK version and API version before proceeding. If no notionVersion is set explicitly, the SDK uses its built-in default (typically 2022-06-28 for current releases).
SDK version history — key milestones:
| SDK Version | Notable Additions |
|---|
2.2.0 | Comments API support (notion.comments.create, notion.comments.list) |
2.2.3 | Status property type in database schemas |
