notion-workspace-core-openapi
Core Notion REST API for searching a workspace, retrieving pages, creating and updating pages, querying data sources, and identifying the connected user. The user supplies a Notion integration or OAuth Bearer token at connection time; no credential is included. Official documentation: https://developers.notion.com/reference/intro
Connect this API to an AI agent Browse all specs
What you can do with notion-workspace-core-openapi 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 |
getCurrentUser | Get the connected user |
| POST | /v1/search |
searchWorkspace | Search a Notion workspace |
| GET | /v1/pages/{page_id} |
getPage | Retrieve a page |
| PATCH | /v1/pages/{page_id} |
updatePage | Update or archive a page |
| POST | /v1/pages |
createPage | Create a page |
| POST | /v1/data_sources/{data_source_id}/query |
queryDataSource | Query a Notion data source |
Authentication
bearerAuth
Bearer token — sent as Authorization: Bearer <token>
Usage guide
Getting credentials
- Create or log in to an account at Notion.
- Create an internal integration or configure an OAuth public connection in the Notion Developer Portal.
- Share the target pages and data sources with the integration using Notion's
Add connectionssetting. - When VX Agent asks for authentication, provide the Notion Bearer token.
Keep the token private. Do not paste it into the Swagger file, marketplace description, prompts, or chat messages.
How to use this API
Use this API to search an authorized Notion workspace, read pages, create pages, update pages, and query structured data sources.
A typical workflow is:
- Use
GET /v1/users/meto verify the connected integration or user. - Use
POST /v1/searchto find pages or data sources and obtain their IDs. - Use
GET /v1/pages/{page_id}to retrieve page properties and metadata. - Use
POST /v1/data_sources/{data_source_id}/queryto query pages in a structured data source with filters, sorts, and pagination. - Use
POST /v1/pagesto create a page under an authorized parent page or data source. - Use
PATCH /v1/pages/{page_id}to update page properties, icon, cover, lock state, or archive status.
Every request must include the Notion-Version header configured in the Swagger file. Use the current version supported by the connection and follow the data source model rather than the deprecated database query endpoint.
Safety and usage notes
Only access pages and data sources that have been explicitly shared with the connected integration. Creating, updating, archiving, locking, or erasing page content changes the user's workspace, so require confirmation before each consequential operation.
Never set erase_content to true unless the user explicitly confirms that all existing page content may be removed. Do not expose private workspace content, integration tokens, customer data, or confidential notes.
Use pagination for large searches and data-source queries. Verify page IDs, parent IDs, property names, and content before creating or updating pages.
Official documentation: Notion API Introduction.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “notion-workspace-core-openapi” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.