Notion

Twin of the Notion API.


Covers	`api.notion.com`
Auth	Integration tokens, OAuth
Webhooks	Yes
Operations	30

Coverage

Pages, databases with data sources and user-defined property schemas, the block tree, data-source query, search, comments and users. The OAuth issuer sits on the same base under /v1/oauth.

Every request carries a Notion-Version header, and it selects the dialect you get. Three are served: 2022-06-28, 2025-09-03 and 2026-03-11.

Credentials

Notion tells developers its tokens are opaque and not to validate their shape, so any non-empty bearer authenticates by default and your existing ntn_… integration token needs no change. Set auth.mode to enforced to accept only the tokens the world knows. See Credentials.

Notion attaches no scopes to a token. Capabilities are the gate instead, and a token without the one a route needs gets a 403 restricted_resource before the resource is even looked up.

Vendor specific details

The Notion-Version header is not optional. Missing it is a 400, and so is an unknown value, both under the code missing_version.
Deleting is always soft. A trashed page still answers a read by id with in_trash: true, but it leaves query and search results, and any write to it other than restoring it is refused.
A page’s properties are validated against its parent data source’s schema, so an unknown property name is a 400 saying it is not a property that exists.
An id that does not exist and one your integration cannot see are the same 404, with the same message about sharing pages. There is no telling them apart.
Real Notion’s default query order, with no sorts, is unstable between runs. The twin serves stable creation order, so an ordering assertion only means something when you pass explicit sorts.

Search here is immediate. On the real vendor the index lags by seconds, so a create-then-search test can be green against the twin and racy in production.

Its own notes

Once a sandbox is running, this twin serves its own operating notes at {control_url}/veris/manual: the credentials it accepts, the API versions it serves, and the fault statuses you can arm against it. They are generated from the same source as its behaviour, so they cannot drift.