Notion is one of the catalog’s quieter profiles — one API, six capabilities — and a useful counter-example to the “API count equals surface size” framing. The interesting thing about the Notion surface isn’t how big it is. It’s how unusual the data model behind it is, and how much of that data model the API actually exposes.
The six capabilities
The Notion API decomposes in the catalog into:
- Blocks — retrieve, append, update, delete blocks. The atomic unit of Notion content.
- Pages — create, retrieve, update, archive pages.
- Databases — create, retrieve, update, query databases.
- Comments — retrieve and create comments on blocks and pages.
- Search — search by title across the workspace.
- Users — list users, retrieve a user.
Six capabilities. Five of them map to familiar nouns (pages, databases, comments, search, users). The interesting one is the first: Blocks.
The block model is the API
Notion’s data model is unusual. A page isn’t a document — it’s a tree of blocks. Every paragraph, every heading, every list item, every table row, every embed, every database view embedded in a page — each is a block, each has a UUID, each is independently addressable. The API exposes that block model directly:
- A page is a container that holds blocks. Creating a page creates a container; appending content means appending blocks.
- Blocks have types, and types nest. A toggle block contains child blocks. A column-list block contains column blocks which contain content blocks. The tree is what the API navigates.
- Databases are themselves a kind of block. A database embedded in a page is reachable through the block API as well as through the database API. The two views are reconciled by the same UUID identifier.
This means the Notion API is structurally closer to a CMS-tree API or a document-fragment API than to the typical SaaS noun-CRUD surface. Working with it well requires internalising the block model first — and the catalog’s per-capability decomposition (Blocks, Pages, Databases as peers) reflects that structural reality rather than hiding it.
What’s interesting about exposing this much
A few things worth noticing about the surface:
- The block model is fully programmable. You can construct an entire Notion page programmatically by emitting the right block tree. That’s the API surface AI-agent-meets-documentation workflows have been waiting for: dump a structured report straight into a Notion page as a real, editable block tree, not a Markdown blob.
- Search is intentionally narrow. The Search capability only searches by title, not by content. That’s a deliberate constraint — full-text search at workspace scale is delegated to the in-product search and to enterprise integrations rather than exposed via the API. The narrow surface is a useful design tell.
- Comments are first-class. A
Commentscapability as a peer toPagesandBlockssays something about how Notion thinks about collaboration — comments aren’t a sidebar feature, they’re a primary surface. Agent workflows that leave human-reviewable annotations on programmatically-generated content can lean on this.
The takeaway
Notion is a useful provider to walk through specifically because it demonstrates that catalog surface area isn’t the same as catalog richness. One API, six capabilities, a block model that’s expressive enough to represent an entire knowledge base programmatically. The capability decomposition in the catalog tells you where the real structural lines are even when the API count understates the surface.
If you’re building integrations that need to write into a knowledge tool rather than just read from one, providers.apis.io/providers/notion is one of the better-shaped surfaces in this category. The block-tree programmability is the part that’s hardest to find in the marketing copy and easiest to find by walking the capability list directly.