Notion

Notion’s workspace API at Notion-Version: 2025-09-03, the version notion-client 3.1.0 sends. That version split every database into a container and one or more data sources, and an integration written before it fails the moment a database it touches gains a second data source: a page can no longer be created “in the database”. Nobody restructures a real workspace to find out whether their integration survives that; this twin holds the state, and the conformance suite drives it through the pinned SDK end to end. Slug: notion

What it models

Area	Modelled
Starting workspace	A shared `Team space` page holding a `Tasks` database with one data source (`Name`, `Status`, `Due`, `Tags`, `Points`, `Overdue`, `Notes`, `Assignee`) and three task pages, plus a `Getting started` page with a few blocks
Authentication	An `ntn_…` internal integration token as a Bearer, checked in Notion’s own order (route, JSON body, token, `Notion-Version`, path identifiers), each refusal in Notion’s words, and a `request_id` on every answer
Databases and data sources	Retrieve, create and update both; a database lists its data sources; a data source’s schema with Notion’s property ids, select options and status groups; renaming or deleting a property carries into its pages
Pages	Create under a data source, a single-source database or a page; the `400` a database with two data sources answers a `database_id` parent; retrieve, update, trash and restore; property items with their own cursor
Property values	Title, rich text, number, select, multi-select (unknown options created), status (unknown options refused), date, checkbox, URL, email, phone, people and relations, each refused in the validator’s own “Fix one” form when wrong; formulas over number properties, count and sum rollups and the created and edited stamps computed when read
Queries and search	Data source queries with filters, compound filters two levels deep, sorts and Notion’s cursor; search over pages and data sources by title
Blocks and comments	Append (including after a sibling and nested children), list, retrieve, update and trash page content; comments on a page, a block or a discussion
Sharing and capabilities	A page never shared with the integration answers exactly like one that does not exist; a missing capability is `403 restricted_resource`

Advancing moves a task’s Status select from To do to In progress to Done, marks a task past its Due date Overdue, and trashes pages a seed marked for cleanup.

Not modelled

The OAuth flow, file uploads, views, custom emojis, data source templates, page markdown and page moves, meeting notes, comment edits and deletes, rich text mentions other than a user’s, two-way relations, formulas beyond arithmetic, rollups other than count and sum, relative date filters, and webhooks. Each endpoint Notion has and the twin has not built answers an explicit 501 in Notion’s envelope; a path Notion does not have gets Notion’s own 400 invalid_request_url. A request naming any Notion-Version other than 2025-09-03 is refused rather than answered in the wrong shapes.

Getting Started

Concepts

Interfaces

Request a twin

What it models

Not modelled

​What it models

​Not modelled

What it models

Not modelled