Notion Databases to Data Sources — which one?
Choose how to modernize integrations after Notion split database container and data source operations, creating a new migration surface that continues into 2026.
Blockers
- replaces: capability/notion-data-source-apis → capability/database-ids
- protocol/notion-api-2022-06-28 incompatible with capability/notion-multi-source-databases
- breaking_change_in: protocol/notion-api-2025-09-03 → capability/notion-search-object-filter-database
- replaces: capability/notion-search-object-filter-data-source → capability/notion-search-object-filter-database
- requires_version: protocol/notion-api-2025-09-03 → package/notionhq-client-v5-0-0
- requires_version: protocol/notion-api-2026-03-11 → package/notionhq-client-v5-12-0
- breaking_change_in: protocol/notion-api-2026-03-11 → capability/notion-block-insertion-after
- replaces: capability/notion-block-insertion-position → capability/notion-block-insertion-after
- breaking_change_in: protocol/notion-api-2026-03-11 → capability/notion-archived-field
- replaces: capability/notion-in-trash-field → capability/notion-archived-field
- breaking_change_in: protocol/notion-api-2026-03-11 → capability/notion-transcription-block
- replaces: capability/notion-meeting-notes-block → capability/notion-transcription-block
Who this is for
- small-team
- low-ops
- enterprise
Candidates
Use a temporary bridge on 2022-06-28, but switch writes to data_source_id now
As of 2026-04-03, Notion says integrations on "2022-06-28" or older still work for databases that have a single data source, and Notion has not announced a minimum-version cutoff for that version family. However, once a connected workspace adds a second data source to a database, old-version requests that rely on database IDs can fail with HTTP 400 validation errors stating that multiple data sources are not supported in that API version. Notion's upgrade guide says some request shapes can already accept a specific "data_source_id" before or after the API-version upgrade, including page creation with a database parent and relation definitions. This makes it a narrow compatibility bridge, not a durable endpoint strategy.
When to choose
Use this when you need the smallest immediate change under low-ops or small-team constraints, but cannot complete the full endpoint migration yet. The decisive factor is whether you only need to stabilize create-page and relation flows while buying time for a broader refactor.
Tradeoffs
Lowest short-term disruption, but it leaves read, query, schema, and search behavior on the legacy model and still exposes you to breakage when users adopt multi-source databases.
Cautions
Do not treat this as a steady-state design. Notion explicitly says database IDs are no longer precise enough once multiple data sources exist, and old-version errors include child data source IDs that you will still need to handle.
Migrate fully to 2025-09-03 data source APIs and SDK v5
As of 2026-04-03, this is the main migration target for integrations that must support Notion's multi-source databases introduced on September 3, 2025. Notion reorganized the API so database-container operations remain under "/v1/databases", while schema, query, and other per-table operations move under "/v1/data_sources"; existing database IDs stay the same, but new data source IDs are required for property management and other table-level work. The upgrade guide also documents search changes: object filters move from "database" to "data_source", and search responses now return data source objects and IDs. For JavaScript and TypeScript clients, Notion recommends upgrading to "@notionhq/client" v5.0.0 or later for dedicated "dataSources" and updated "databases" methods.
When to choose
Use this when you need the correct long-lived model for new Notion workspaces, shared enterprise integrations, or any product where users may create additional data sources under one database container. The decisive factor is whether your integration reads, queries, or mutates schema, because those paths now depend on the data source abstraction.
Tradeoffs
This is the durable fix for the September 2025 model split, but it requires endpoint remapping, object-shape updates, search changes, and likely SDK upgrades.
Cautions
Creating a database still uses the database API, but initial schema now lives under "initial_data_source[properties]". Retrieve Database now returns child data sources, while schema details come from Retrieve Data Source. Webhooks also became versioned, so API and webhook rollout should be coordinated.
Complete the data source migration, then standardize on 2026-03-11
As of 2026-04-03, "2026-03-11" is the newer Notion API version after the data-source split, and Notion describes its breaking changes as smaller follow-on changes rather than a new data-model rewrite. The upgrade guide says it changes block insertion from "after" to a "position" object, renames "archived" to "in_trash" in REST requests and responses, and renames the "transcription" block type to "meeting_notes". Notion recommends "@notionhq/client" v5.12.0 or later for this version. For webhooks, Notion says the "2026-03-11" subscription version is available, but event payloads are unchanged from "2025-09-03".
When to choose
Use this when you are already committing to the data source model and want one current-version baseline for new work in 2026. The decisive factor is whether you prefer doing the small cleanup now instead of landing on "2025-09-03" and carrying another near-term version hop.
Tradeoffs
Best for reducing near-future version churn, but it adds one more migration checklist on top of the mandatory database-to-data-source refactor.
Cautions
This is not a shortcut around the September 2025 changes. You still must migrate to data source IDs and data source endpoints first; "2026-03-11" only layers additional request and field renames on top.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Notion Databases to Data Sources — which one?"