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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Notion bearer integration secrets are stored encrypted in the Jentic vault. Agents receive scoped execution access — the raw integration secret never enters the agent's prompt or context.
Intent-based discovery
Agents search Jentic by intent (e.g. 'create a Notion page' or 'query a Notion database') and Jentic returns the matching operation with its input schema attached.
Time to first call
Direct Notion integration: 1-2 days for auth, block tree handling, and database filters. Through Jentic: under an hour — search, load schema, execute.
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 at https://app.jentic.com/sign-up.
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.
GET STARTED