> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Databases, data sources, pages, blocks and comments, at version 2025-09-03

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.