The data_sources migration: Notion’s biggest API break

Per Notion’s official upgrade guide (as of July 2026), version 2025-09-03 introduces first-class multi-source databases — one database can now hold several tables — and reshapes the API around that:

• A database is now a container with a data_sources array; the property schema and the rows live on each data_source.
• Querying and schema updates move from /v1/databases to /v1/data_sources; retrieving a database returns pointers, not properties.
• Creating a page under a database now takes a data_source_id parent instead of a database_id, and parent objects gain a data_source_id field.
• Webhook events are renamed — database.content_updated becomes data_source.content_updated, database.schema_updated becomes data_source.schema_updated — with new data_source.created/moved/deleted events. Subscriptions must be updated to receive the new shapes.

The sharpest edge is what happens to integrations pinned to older versions: the moment a user adds a second data source to a database, the guide says creating pages under it, reading, writing, or querying it, and writing relation properties that point to it all fail. Pinning your Notion-Version header buys time only until one user clicks “add data source.”

# Before: schema and rows hang off the database
GET  /v1/databases/{database_id}          # returns properties
POST /v1/databases/{database_id}/query    # returns rows

# After: the database is a container; go through the data source
GET  /v1/databases/{database_id}          # returns data_sources: [{id, name}]
GET  /v1/data_sources/{data_source_id}    # returns properties
POST /v1/data_sources/{data_source_id}/query

Breaking changes are abstract until you read the support threads. Every citation below is a real, verified thread:

• Read the official upgrade guide end-to-end before touching code; the parent-object changes are easy to miss.
• Discover and persist data_source_id for every database you touch — treat database_id as a container key only.
• Update webhook subscriptions and handlers for the renamed data_source.* events; the old database.* names stop matching reality.
• Test against a database that actually has two data sources — the failure mode only appears when a user adds one.
• If you depend on a no-code platform (Zapier, n8n, Make), pin your Zaps/nodes to the legacy integration version until the vendor’s migration is confirmed stable — and accept that a user adding a data source can still break you.

One mercy, per Notion’s own upgrade FAQ (July 2026): “We don’t currently have any process for halting support of old Notion API versions” — old versions keep working against single-data-source databases. The cliff is per-database and user-triggered, not a dated shutdown.

We build a board API for a living, so an honest read: the data-source model itself is defensible — multi-table databases are a real feature. The damage came from how the change moved through the ecosystem: a core resource changed identity, and every consumer had to rediscover it at once.

Novum OS’s API design takes the opposite bets:

• Versioned, additive-first. Everything lives under /v1; changes ship additive (new fields, new endpoints). A reshape of that magnitude would be a new version running alongside, not a shift under your integration.
• Webhook payloads carry the changed fields inline, delivered at-least-once with idempotency keys. Consumers that don’t chase follow-up fetches have far less surface area exposed to endpoint reshapes — see why diff-less payloads cost double.
• One concept for the board. A board is a board — columns and status groups are first-class, editable via the API, with no container/schema split for integrations to re-learn.