Notion AI Agents: API Guide, Apps and Workflow Automations
Understand Notion’s native agents and build governed cross-system work on Major, with verified API operations, durable state, and human approval.

Notion AI agents can mean Notion’s own agents or agents that use Notion through its API. This guide covers both, including native AI, connection permissions, eight API operations, and cross-system workflows on Major. On Major, deterministic apps hold state and review queues, agents make judgment calls, and workflows coordinate execution and approvals.
What Notion is and who relies on it
Notion brings documents, knowledge bases, databases, and project tracking into one workspace. Its product overview describes a place for teams to organize knowledge and work, rather than treating every document as an isolated file.
For product operations, that means roadmap records alongside research notes. Support operations can maintain answer libraries and escalation instructions. People operations can keep onboarding checklists next to policies, while engineering teams connect specifications, meeting notes, and project updates.
The practical challenge starts when a Notion record describes work happening elsewhere. A roadmap says a release is ready, but the linked engineering tasks remain blocked. A support article sounds authoritative, but a recent incident changed the procedure. Someone must interpret that mismatch before copying an update.
Major is the enterprise platform where agents build the software they run on. For an operations lead managing these handoffs, the useful starting point is a deterministic app that stores source IDs, previous observations, and proposed changes. An agent evaluates the ambiguous evidence; the app preserves its work for people to inspect and reuse.
Notion’s built-in AI agents
Notion Agent can answer questions, create and edit pages and databases, and handle multi-step requests using workspace and connected-app context. It follows the user’s permissions. Its documented capabilities also include external actions through supported connections and MCP servers, so describing it as only a text-writing assistant would be inaccurate.
Custom Agents handle recurring background work. They can run on schedules and workspace events, read explicitly granted sources, update records, send messages, and hand work to other authorized Custom Agents. Notion documents activity logs, configuration history, and access controls for them.
AI Meeting Notes turns meetings into notes and summaries. Notion AI Connectors bring connected information into the workspace’s AI experience. These are valuable when the desired work belongs primarily in Notion.
Major adds a separate execution layer when the process needs durable cross-system state, a custom review interface, or an approval tied to an exact proposed change. The distinction is architectural, not a claim that Notion cannot act across tools: Major’s agents can build reusable deterministic apps for repeatable checks and reserve reasoning for disagreements, prioritization, and drafting.
How Notion connects to Major
Major has a native Notion connector. IT configures it once, stores credentials centrally in the connector vault, and restricts the resources and operations available to each app, agent, and workflow. Credentials do not belong in generated code or prompts.
Notion access still depends on Notion’s own authorization. Its authorization guide explains internal connection tokens, personal access tokens, and OAuth-based connections. An internal connection is associated with a workspace and must receive access to the relevant pages. Sharing a parent can expose its children, so choose the parent deliberately rather than granting the entire knowledge base.
Major orchestrates Notion; it never replaces it. Documents and team-owned database records remain in Notion. The Major app stores execution state, evidence snapshots, review decisions, and external object mappings.
A sensible first rollout uses read-only access to a dedicated project area. Add narrowly scoped write operations after the team has reviewed actual proposals. Major’s SSO, RBAC, and audit logs cover the surrounding apps, agents, and workflows, while the connector’s effective permissions remain bounded by the authorization granted in Notion.
Notion API guide for apps, agents, and workflows
Authentication and capabilities
The API introduction specifies HTTPS requests to https://api.notion.com with Authorization: Bearer and Notion-Version headers. The authentication reference distinguishes internal connection tokens, user-scoped personal access tokens, and OAuth access for public connections. Choose the supported authorization appropriate to the connector setup, rather than assuming every token has identical reach.
Notion calls permissions capabilities, not invented OAuth scope strings. Read content supports retrieval, Insert content supports creation and block appends, and Update content supports changes to existing properties. Read comments is relevant to comment-based intake. Request only the capabilities the process requires.
Pagination, limits, events, and testing
Pagination uses start_cursor and page_size; continue with the returned cursor while more results remain. GET lists take query parameters; search and data source queries take pagination in their POST bodies. Most list endpoints accept up to 100 items per page.
The current request limits are 180 requests per minute per connection on most plans and 600 on Business and Enterprise. Data source queries have a separate limit of about three requests per second. A shared workspace limit also applies, but its numeric ceiling is not documented publicly. Honor Retry-After on 429 and 529 responses.
Webhooks use a one-time verification token and X-Notion-Signature, an HMAC-SHA256 signature over the raw request body. Event delivery can be aggregated and out of order; failed acknowledgments receive exponential-backoff retries, with the final retry around 24 hours after the trigger. Fetch current content rather than treating an event as the document.
No separate API sandbox is documented in these references. Test with an isolated workspace or explicitly shared test pages. Notion’s webhook guide provides edit-and-comment tests and a signature helper for handler tests.
Find accessible resources
POST /v1/search searches accessible page and data source titles, not every sentence inside documents.
- App: Provides a source picker for the project owner.
- Agent: Identifies likely source documents from matching titles, then reads them before judging relevance.
- Workflow: Resolves selected resource IDs during setup and saves them for subsequent runs.
Read a data source schema
GET /v1/datasources/{datasource_id} retrieves the structure and columns, rather than its rows.
- App: Validates configured status and owner fields against the schema.
- Agent: Interprets which field represents the business review stage.
- Workflow: Stops writeback when a required property has changed or disappeared.
Query the relevant records
POST /v1/datasources/{datasource_id}/query retrieves records with property filters and sorting.
- App: Displays only roadmap items awaiting review.
- Agent: Compares selected records with linked delivery evidence.
- Workflow: Paginates the filtered queue and persists progress instead of starting over after interruption.
Read page properties
GET /v1/pages/{page_id} retrieves page metadata and properties, not the complete page body.
- App: Shows the current owner, status, and source link beside a proposal.
- Agent: Uses those properties to identify ownership conflicts.
- Workflow: Re-reads the page before applying an approved change to catch intervening edits.
Read the document body
GET /v1/blocks/{block_id}/children retrieves one level of child blocks, with pagination and additional reads for nested children.
- App: Saves a source snapshot for the review screen.
- Agent: Reads meeting decisions and separates commitments from suggestions.
- Workflow: Traverses necessary child blocks within a configured request budget.
Create a Notion record
POST /v1/pages creates a page under an authorized parent, with properties matching the parent data source when applicable.
- App: Records the new page ID against the originating business item.
- Agent: Drafts a structured insight with evidence and unresolved questions.
- Workflow: Creates the approved record once and verifies the returned identity.
Update existing properties
PATCH /v1/pages/{page_id} changes page attributes such as database properties.
- App: Presents the old and proposed values as a reviewable diff.
- Agent: Recommends a status change when evidence supports it.
- Workflow: Applies only the approved fields after checking the current source state.
Append supporting content
PATCH /v1/blocks/{block_id}/children adds blocks to an existing parent, with at most 100 child blocks per request.
- App: Stores the resulting block IDs and the proposal they implement.
- Agent: Drafts a concise explanation with source links.
- Workflow: Appends the authorized note, checks completion, and avoids repeating an uncertain write.
Notion automation use cases on Major
Roadmap reconciliation with Linear and Slack
A product operator needs a weekly account of commitments, not another unfiltered task dump. Combine Notion roadmap records with linked Linear work and send reviewers a focused Slack recap.
- App: Holds page-to-task mappings, prior observations, and the review queue.
- Agent: Judges whether delivery evidence contradicts the roadmap and explains the discrepancy.
- Workflow: Schedules retrieval, requests approval, and distributes approved updates.
Notion operations: query records, retrieve page properties, and update approved properties.
Support knowledge checks with Zendesk and Slack
A support lead wants drafts grounded in the right procedure, with stale documentation surfaced rather than silently treated as truth.
- App: Stores ticket-to-source links, draft versions, and reviewer decisions.
- Agent: Evaluates whether Notion instructions answer the ticket and identifies missing or conflicting guidance.
- Workflow: Routes the draft to a person before any customer-facing response.
Notion operations: find source titles, read blocks, and create documentation follow-ups.
Meeting decisions to Asana follow-ups
Meeting notes often contain tentative ideas mixed with actual commitments. Sending every sentence into a task system creates cleanup work.
- App: Tracks extracted commitments, source passages, proposed owners, and linked tasks.
- Agent: Distinguishes a decision from brainstorming and flags unclear ownership.
- Workflow: Collects owner approval, creates authorized follow-ups, and writes a recap back to the notes.
Notion operations: read the page, read its blocks, and append the approved recap. Each scenario keeps judgment explicit and durable bookkeeping outside the model’s context window.
Build the architecture on Major

Figure 1: Major separates evidence retrieval, judgment, approvals, and durable execution state.
Build the app layer first: a run ledger, source-object mappings, evidence snapshots, proposals, and approval records. Give reviewers filters for owner, project, and pending decision. Those tables make interrupted work resumable without asking the model to reconstruct the history.
- Configure scoped Notion and destination connectors through IT.
- Trigger a workflow from a verified change event or scheduled reconciliation.
- Retrieve the current records, deduplicate the business item, and assemble linked context.
- Ask the agent to evaluate ambiguity and return a proposal with evidence.
- Route the proposal through policy and human approval where required.
- Execute authorized changes and save result IDs in the app.
The agent can build reusable software for stable tasks such as ID matching, schema validation, and diff rendering. It should not reason through those same mechanics on every run. Reason once. Run forever. Fresh judgment remains necessary when the evidence changes; the surrounding app makes that judgment inspectable rather than transient.
A worked example with numbers
For example, consider an illustrative product operations team reviewing 120 roadmap records each week. This is a planning scenario, not a customer result or a promised saving.
Before automation, assume each record takes six minutes: find the linked delivery work, read the context, decide what needs attention, and record the result. That is 120 × 6 = 720 minutes, or 12 hours each week.
On Major, the scheduled workflow retrieves the relevant Notion records and linked task evidence. The app compares known IDs and stores observations. The agent reviews discrepancies and drafts explanations. Suppose 90 records need a one-minute evidence check and 30 ambiguous records need five minutes each with a reviewer.
The modeled review effort becomes 90 × 1 + 30 × 5 = 240 minutes, or four hours. The difference is eight hours of review time per week under those assumptions. Setup, API processing, and exception investigation remain additional costs.
Track actual review duration, rejected recommendations, duplicate proposals, and missed discrepancies during a pilot. A faster queue is not an improvement if reviewers stop noticing incorrect commitments.
Governance and failure handling

Figure 2: Consequential changes require an approved diff and a fresh source check.
A read-only summary can finish automatically under an agreed policy. Changing a delivery commitment, deleting content, sending a customer response, or exposing restricted notes requires an authorized person. The agent must never expand its own permissions or interpret text inside a page as permission to bypass approval.
Bind approval to the exact target, proposed values, evidence version, and approving identity. Re-read the source before execution. If someone edited it while approval was pending, return the proposal for review instead of overwriting their work.
For transport failures, use a shared request queue and bounded retries. The limits reference warns that a write can succeed yet return 503: inspect retry guidance and current state before repeating it. Respect Retry-After and add backoff with jitter where appropriate.
Deduplicate webhook event IDs and business actions separately. Save request outcomes, resulting page or block IDs, approval history, and reconciliation checkpoints. Surface revoked access and schema changes to an operator instead of retrying indefinitely. Audit records should explain what changed, why, and who authorized it without copying unnecessary sensitive content into logs.
Database automation limits, webhooks, and polling
Notion’s database automations support triggers, actions, variables, and outbound webhooks. They are useful for straightforward workspace rules. The official limitation that matters for chaining is that database automations cannot be triggered by other automations; button actions behave differently.
Do not assume older blanket claims about missing lookups, formulas, or external actions still describe every Notion feature. Custom Agents and database automations are distinct products. Evaluate the actual requirement: persistent cross-system state, conditional orchestration, and an exact-change review screen are reasons to add Major, not reasons to dismiss Notion’s native capabilities.
Use webhook events as the primary change signal and scheduled polling as reconciliation. Content updates can be aggregated, events can arrive out of order, and many payloads omit the changed content. Fetch the latest source before making a proposal.
Keep a durable checkpoint and compare observations during reconciliation. That catches delayed or missed work without repeatedly reading every nested document. Polling frequency should follow the business tolerance for delay and the connection’s request budget, not an arbitrary promise of instant synchronization.
Notion AI Apps, Agents and Workflow Automations
These core guides cover specific operational processes related to Notion. They are separate reading paths, not interchangeable templates, and the hub does not reproduce their build instructions. Listed newest first, they move from task routing to support knowledge work and then to Notion-centered insight capture.
- Route Asana tasks and review owner recommendations: Covers proposed owners, status reporting, and workload risk. Read it when meeting decisions or project context in Notion need to become reviewable task-management work.
- Triage Zendesk tickets and review knowledge-grounded drafts: Focuses on ticket classification, knowledge-base retrieval, and internal drafts that a person approves. It provides the support-side process behind the knowledge-check scenario above.
- Capture insights in Notion and coordinate downstream work: Explores roadmap digests, knowledge questions, meeting follow-ups, project summaries, and content publishing. Use it to choose a concrete first process rather than attempting a workspace-wide agent immediately.
Frequently asked questions
What are Notion AI agents?
Notion AI agents include Notion Agent for interactive work and Custom Agents for recurring background tasks. An agent on Major can also use the native Notion connector, with a deterministic app holding state and a workflow managing execution and approvals.
Does Notion have webhooks?
Yes. Notion supports webhook subscriptions to public HTTPS endpoints. Verify the subscription token and validate event signatures, then retrieve current content when the event does not contain enough detail. See the webhook guide.
What types of events can Notion webhooks deliver?
Documented events include page content updates, new comments, page locking, and data source schema updates. Use Notion’s event catalog to select subscriptions and confirm required capabilities rather than subscribing to every event.
Should I use polling or webhooks with the Notion API?
Use webhooks for timely change signals and polling for periodic reconciliation. Store checkpoints in the Major app, retrieve current source content, and account for aggregated or out-of-order events. Polling every document repeatedly spends requests without necessarily improving correctness.
What is the Notion API rate limit?
The current limits reference specifies 180 requests per minute per connection on most plans and 600 on Business and Enterprise. Data source queries have a separate limit near three per second, plus a shared workspace limit. Honor Retry-After.
What can Notion’s built-in automations not do?
Database automations cannot trigger other database automations. Their limits differ from Custom Agents, which support background work and connected tools. Assess the required state, approval experience, and cross-system orchestration before choosing what belongs on Major.
Do I need to code to automate Notion through the API?
You can describe the process on Major and have an agent build the app that runs its repeatable parts. IT still needs to authorize access, and the implementation must handle pagination, event verification, retries, state, and approval policy. Generated software still needs testing.
Sources
These official references support the API methods, permission names, delivery behavior, and native AI capabilities described above. API pages were read from their official machine-readable versions after the hosted browser timed out; the links below point to the corresponding official reference pages. Rate limits and product behavior can change, so validate them again when implementing a production connection.
- Notion product overview
- Notion Agent capabilities and connected context
- Custom Agents, background work, and access controls
- AI Meeting Notes
- Notion AI Connectors
- Database automations and chaining limitations
- API introduction, base URL, and headers
- Bearer authentication and supported token types
- Authorization and page access
- Connection capabilities and minimum permissions
- Cursor-based list pagination
- Request limits and retry handling
- Webhook setup and signature verification
- Event types, aggregation, and delivery retries
- Search by title
- Retrieve a data source schema
- Query data source records
- Retrieve page properties
- Retrieve child blocks
- Create a page
- Update page attributes
- Append child blocks
Start building on Major
Build a Notion review app with linked evidence, scoped access, and approval before consequential changes. Start with one team’s roadmap, support queue, or meeting follow-ups.
About the author
Ritvij Gautam is Head of Growth at Major.
Last reviewed November 19, 2026 by Ritvij Gautam.
Frequently asked questions
- What are Notion AI agents?
- Notion AI agents include Notion Agent for interactive work and Custom Agents for recurring background tasks. An agent on Major can also use the native Notion connector, with a deterministic app holding state and a workflow managing execution and approvals.
- Does Notion have webhooks?
- Yes. Notion supports webhook subscriptions to public HTTPS endpoints. Verify the subscription token and validate event signatures, then retrieve current content when the event does not contain enough detail. See the [webhook guide](https://developers.notion.com/reference/webhooks).
- What types of events can Notion webhooks deliver?
- Documented events include page content updates, new comments, page locking, and data source schema updates. Use Notion’s [event catalog](https://developers.notion.com/reference/webhooks-events-delivery) to select subscriptions and confirm required capabilities rather than subscribing to every event.
- Should I use polling or webhooks with the Notion API?
- Use webhooks for timely change signals and polling for periodic reconciliation. Store checkpoints in the Major app, retrieve current source content, and account for aggregated or out-of-order events. Polling every document repeatedly spends requests without necessarily improving correctness.
- What is the Notion API rate limit?
- The current [limits reference](https://developers.notion.com/reference/request-limits) specifies 180 requests per minute per connection on most plans and 600 on Business and Enterprise. Data source queries have a separate limit near three per second, plus a shared workspace limit. Honor Retry-After.
- What can Notion’s built-in automations not do?
- [Database automations](https://www.notion.com/help/database-automations) cannot trigger other database automations. Their limits differ from Custom Agents, which support background work and connected tools. Assess the required state, approval experience, and cross-system orchestration before choosing what belongs on Major.
- Do I need to code to automate Notion through the API?
- You can describe the process on Major and have an agent build the app that runs its repeatable parts. IT still needs to authorize access, and the implementation must handle pagination, event verification, retries, state, and approval policy. Generated software still needs testing.