canonical: https://jentic.com/apis/notion.com/notion # Notion API Jentic publishes the only available OpenAPI specification for Notion API, keeping it validated and agent-ready. Notion is a workspace combining notes, databases, and project tracking inside a single block-based document model. The API exposes 42 endpoints covering pages, databases, blocks, users, comments, files, and views, including markdown-aware page reads and writes. It supports the operational tasks of programmatically reading workspace content, creating pages and databases, manipulating block trees, and integrating Notion with other systems. ## For AI agents Read and write Notion pages, databases, blocks, comments, and files; supports markdown reads, page moves, and database queries. ## Scope Does not handle real-time presence, calendar scheduling, or video calls - use for Notion pages, databases, blocks, and comments only. ## Capabilities - Create, read, update, and move Notion pages within a workspace - Read pages as markdown and write pages from markdown via the dedicated endpoint - Query databases with filters and sorts to retrieve matching pages - Append, update, and delete blocks within a page's block tree - Manage comments on pages and blocks - List workspace users and bot information for permission context ## Use cases ### Notion as a Knowledge Source for AI An AI assistant pulls Notion pages as markdown to ground its answers in the team's working documents. The /v1/pages/{page_id}/markdown endpoint returns ready-to-feed text without needing the agent to walk the block tree, which dramatically simplifies retrieval-augmented workflows over Notion content. Example prompt: Fetch the markdown of the 'Engineering Runbook' page and use it as context to answer an on-call question ### Database-Driven Project Tracking An automation queries a Notion task database for items assigned to a user with a due date this week, creates a daily summary page, and links the open tasks. The /v1/databases/{database_id}/query endpoint applies filters and sorts server-side; /v1/pages creates the summary and /v1/blocks/{block_id}/children appends the task list. Example prompt: Query a Notion task database for items due this week assigned to a user, then create a summary page listing those tasks with links ### Two-Way Document Sync A documentation pipeline writes Notion pages from a markdown source of truth and pulls back edits as markdown for review. The markdown read and write endpoints make round-tripping practical without translating block structures by hand, while comment endpoints surface reviewer feedback for triage. Example prompt: Update a Notion page from a markdown file via PATCH /v1/pages/{page_id}/markdown, then read back any comments left by reviewers ### AI Agent Notion Operator An AI agent helping a knowledge worker creates pages, moves pages between parents, appends checklists, and queries databases on request. Through Jentic, the agent searches for the right Notion operation, loads the schema, and calls /v1/pages, /v1/blocks/{block_id}/children, or /v1/databases/{database_id}/query as the request requires. Example prompt: Create a new Notion page titled 'Meeting Prep', append three checklist blocks for the agenda, and move the page under the Weekly Meetings parent ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/pages | Create a page | | GET | /v1/pages/{page_id} | Get a page | | GET | /v1/pages/{page_id}/markdown | Get a page as markdown | | PATCH | /v1/pages/{page_id}/markdown | Update a page via markdown | | PUT | /v1/pages/{page_id}/move | Move a page to a new parent | | PATCH | /v1/blocks/{block_id}/children | Append child blocks to a page or block | | GET | /v1/blocks/{block_id}/children | List child blocks | ## Key resources - **Pages** — Create, read, update, move, and delete pages, including markdown reads and writes - **Databases** — Create, query, and update databases that hold structured pages - **Blocks** — Read and modify the block tree that makes up page content - **Users** — List workspace users and retrieve bot information - **Comments** — Manage comments on pages and blocks - **Files** — Upload and retrieve files attached to Notion content ## Why Jentic - **Setup:** Wiring Notion by hand means setting up its bearer integration secret against api.notion.com and threading it through page, block, and database calls yourself. Through Jentic you install once, import the Notion API from the API Directory, store the secret once, and your agent calls it. - **Permission scoping:** Notion puts the page and block ids in the URL path (/v1/pages/{page_id}, /v1/blocks/{block_id}/children), so a rule can pin your agent to one page or block. You choose the operations it may call, so moving a page or patching markdown is not included unless you add it. - **Credential handling:** Your Notion integration secret is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a Notion page' or 'append blocks to a page', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Coda API** — Coda combines docs and tables in a similar all-in-one workspace model. - **Airtable API** — Airtable focuses on structured databases with views, while Notion is doc-first with database support. - **Atlassian Jira API** — Pair Jira issue tracking with Notion documentation for engineering workflows. ## FAQ ### Why is there no official OpenAPI spec for Notion API? Notion does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Notion API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Notion API use? Notion uses HTTP bearer authentication with an integration secret. Through Jentic, the bearer token is stored in the vault and injected at execution time, so the agent never sees the raw integration secret. ### Can I read a Notion page as markdown with this API? Yes. GET /v1/pages/{page_id}/markdown returns the page rendered as markdown, which avoids walking the block tree manually. PATCH on the same path lets you update a page from a markdown source. ### What are the rate limits for the Notion API? Notion's public documentation notes an average of three requests per second per integration. The OpenAPI spec does not encode this - implement an exponential backoff on 429 responses and check the latest Notion developer docs for current limits. ### How do I query a Notion database through Jentic? Search Jentic for 'query a Notion database'. Jentic returns the database query operation with its filter and sort schema, so the agent submits a structured filter directly without browsing the Notion docs. ### Can I move a Notion page to a different parent? Yes. PUT /v1/pages/{page_id}/move accepts a new parent reference and reparents the page. This is useful for restructuring workspaces or archiving completed work. ### Can I limit what my agent is allowed to do with the Notion API? Yes. Because you self-host Jentic One, your own rules decide which Notion operations the agent may call, so you can allow reading a page as markdown or querying a database while excluding page moves via PUT /v1/pages/{page_id}/move or markdown writes via PATCH /v1/pages/{page_id}/markdown. Notion carries the page and block ids in the URL path, such as /v1/pages/{page_id} and /v1/blocks/{block_id}/children, so a rule can pin the agent to a single page or block. The agent can only reach the operations and credentials you have granted, and nothing else runs.