OpenAPI Marketplace · Productivity & Project Management

Notion Pages & Databases

Name: Notion Pages & Databases
Author: vx.ai

v1.0.0 · 13 endpoints · 0 connections · shared by vx.ai

Before stand-up, pull this week's open tasks from a Notion data source with filters and sorts, read the spec page behind each one as markdown, then file new rows, update status properties, append notes or leave a comment, all on pages shared with your integration.

Connect this API to an AI agent Browse all specs

What you can do with Notion Pages & Databases via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/v1/users/me`	getBotUser	Check the token and see the integration's bot user and workspace
GET	`/v1/users`	listUsers	List people in the workspace (for person properties and mentions)
POST	`/v1/search`	search	Search pages and data sources shared with the integration by title
GET	`/v1/pages/{page_id}`	getPage	Get a page's properties, parent and URL
PATCH	`/v1/pages/{page_id}`	updatePage	Update a page's properties, icon or cover
GET	`/v1/pages/{page_id}/markdown`	getPageMarkdown	Read a page's content as markdown
GET	`/v1/blocks/{block_id}/children`	listBlockChildren	List the content blocks inside a page or block
PATCH	`/v1/blocks/{block_id}/children`	appendBlockChildren	Append paragraphs, to-dos or other blocks to a page
GET	`/v1/data_sources/{data_source_id}`	getDataSource	Get a database's data source schema (property names and types)
POST	`/v1/data_sources/{data_source_id}/query`	queryDataSource	Query database rows with filters and sorts
POST	`/v1/pages`	createPage	Create a page under a page or as a new row in a data source
GET	`/v1/comments`	listComments	List open comments on a page or block
POST	`/v1/comments`	createComment	Comment on a page or reply in a discussion

Authentication

bearerAuth

Bearer token — sent as Authorization: Bearer <token>

Notion integration secret (or OAuth access token), sent as Authorization: Bearer <token>.

How to get a credential

Open notion.so/profile/integrations and click New integration (internal).
Pick the workspace, name it, and under Capabilities enable Read content, Update content, Insert content and, if you want comments, Read/Insert comments.
Copy the Internal Integration Secret (ntn_...).
In Notion, open each page or database the agent should see, click ••• > Connections and add your integration. Pages that are not shared stay invisible (404).

Permissions used

Capability	Operations
Read content	search, getPage, getPageMarkdown, listBlockChildren, getDataSource, queryDataSource
Insert content	createPage, appendBlockChildren
Update content	updatePage
Read / insert comments	listComments, createComment
User information	getBotUser, listUsers

Common errors

Status	Meaning	Fix
401	Secret missing, revoked or mistyped	Copy the secret again from the integration settings
403	The integration lacks a capability (e.g. insert comments)	Enable it under Capabilities
404	Page or data source not shared with the integration, or wrong id	Add the integration under ••• > Connections
400	Invalid property name/type, bad filter, or wrong Notion-Version	Read the schema with getDataSource; send Notion-Version 2026-03-11
429	Rate limited (180 requests per minute per connection; 600 on Business and Enterprise)	Wait for Retry-After seconds and retry

Store the secret as a VX Agents credential (bearer token) so it is never pasted into chats or prompts.

Usage guide

Setup

Credential: an internal integration secret (notion.so/profile/integrations), stored as a VX Agents bearer-token credential. Share every page or database the agent needs with the integration (••• > Connections), or it gets 404.
The Notion-Version header is pinned to 2026-03-11. Worth pinning: the data_source_id of the task or CRM database you work in.

Work a database

getBotUser to confirm the token works.
search with query and filter {"property": "object", "value": "data_source"} to find the database's data source (or "page" for pages).
getDataSource to read the property names and types; filters and writes must use these exact names.
queryDataSource with filter (e.g. {"and": [{"property": "Status", "status": {"does_not_equal": "Done"}}, {"property": "Due", "date": {"on_or_before": "2026-10-20"}}]}) and sorts ([{"property": "Due", "direction": "ascending"}]).
Read a row's page: getPage for properties, getPageMarkdown for the body as markdown (or listBlockChildren for raw blocks).
After the user confirms:
- new row: createPage with parent {"type": "data_source_id", "data_source_id": "..."}, properties, and optional markdown for the body;
- change fields: updatePage with only the properties that change;
- add notes: appendBlockChildren on the page id with up to 100 blocks;
- discuss: listComments with block_id = page id, createComment with parent.page_id (or discussion_id to reply) and rich_text.

Good to know

Property values follow their type: title/rich_text take rich-text arrays, status/select take {"name": "..."}, date takes {"start": "2026-10-16"}, people takes [{"id": "<user id>"}] (ids from listUsers).
Ids are UUIDs with or without dashes; a page URL ends with its id.
Lists page with start_cursor = next_cursor from the previous response, up to page_size 100.
Rate limit: 180 requests per minute per connection (600 on Business and Enterprise); on 429 wait for Retry-After.
Edits are visible to the whole workspace and may notify people: confirm with the user before createPage, updatePage, appendBlockChildren or createComment. This spec cannot archive or delete anything.
queryDataSource.filter and block children are simplified objects here; follow the shapes in the examples above.

Source: Notion API reference (https://developers.notion.com/reference/intro), checked 2026-10-16.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Notion Pages & Databases” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.