Notion API
★ Only Publicly Available OpenAPI DocumentProductivityCollaborationbearer42 EndpointsREST
For Agents
Read and write Notion pages, databases, blocks, comments, and files; supports markdown reads, page moves, and database queries.
Use for: I want to create a new Notion page in a specific parent page, Search for pages and databases matching a keyword, Get the markdown of a Notion page for processing, Query a Notion database for tasks assigned to a teammate
Not supported: Does not handle real-time presence, calendar scheduling, or video calls - use for Notion pages, databases, blocks, and comments only.
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.
Install Jentic One Beta
Connect the Notion API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Notion API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnotion.com%2Fnotion" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnotion.com%2Fnotion" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Notion API.
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
Patterns agents use Notion API for, with concrete tasks.
★ 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.
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.
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.
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.
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
42 endpoints — jentic publishes the only available openapi specification for notion api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Notion API through Jentic.
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.
GET STARTED