Most teams connect their first agent to Notion in ten minutes, then discover a week later that it either sees the entire workspace or silently reads only the first hundred rows of a database. This guide is the safe path from the start: an internal integration, the narrowest capabilities, page-level sharing, and the handful of data-model and rate-limit facts that decide whether the agent works. The steps are framework-agnostic; the same shape works for LangChain, LlamaIndex, the OpenAI Assistants API, a custom agent, or Gravity.

Notion's developer documentation is the source of truth for endpoint behavior, capabilities, and limits (developers.notion.com, retrieved 2026-07-01). Where this guide and Notion's docs disagree, trust Notion's docs, because the API evolves. This is a companion to our other integration walkthroughs, including connecting an agent to Slack and connecting an agent to a database.

Internal vs public integration

Notion offers two integration types, and the choice sets everything downstream. An internal integration lives inside a single workspace, authenticates with one secret token, and is the right choice for an agent that works on your own Notion. A public integration uses OAuth so it can connect to other people's workspaces, and it is only worth the extra consent-and-token machinery if you are shipping a product that customers install into their own Notion.

For almost every internal automation, an owner-operator agent or a team assistant, the internal integration is the correct and simpler path. Choose it unless you are explicitly building for external workspaces.

The minimum capability set

Grant the least the agent will actually use. Notion integrations declare capabilities, and over-granting is the quiet way an agent ends up able to rewrite content it should only read. The core capabilities:

CapabilityWhy
Read contentFetch pages, blocks, and database rows. Enough on its own for a summarizing or reporting agent.
Insert contentAdd new pages, rows, or blocks. Needed for an agent that files or creates records.
Update contentEdit existing pages and properties. The highest-risk capability; grant only when the agent edits in place.
Read commentsOptional. Only if the agent reasons over discussion threads.
Insert commentsOptional. Only if the agent should reply in comments.
Read user informationResolve people. Prefer the option without email unless a feature truly needs the email address.

A good default for a first agent is read content only. You can widen capabilities later from the integration settings; starting narrow means an early prompt mistake cannot alter your workspace. The same least-privilege principle applies to every connection; see how to limit agent actions.

Create the integration

Steps using Notion's integration settings:

  1. Go to notion.so/my-integrations and create a new integration. Choose the internal type and associate it with your workspace.
  2. Set the capabilities from the table above. Start with read content; add insert or update only if this agent writes back.
  3. Copy the integration secret (the internal token). Store it in your secret manager. Never paste it into code or a prompt.
  4. In your agent's HTTP client, send the token as a Bearer authorization header and set the required Notion-Version header on every request. Pin a specific API version so an upstream change does not silently alter behavior.
  5. Test with a single read call against one shared page (the next section covers sharing) before you let the agent loose on a database.

Rotate the token if it is ever exposed, and on a schedule for production use. An agent that caches the token forever and never refreshes will fail the day it is rotated, so plan rotation into your secret store from the start.

Share only the pages it needs

This is the security control that matters most, and it is Notion's strongest feature for safe agents. An integration sees nothing by default. It gains access only to the pages and databases you explicitly connect it to, and that access flows down to child pages but never up to parents or siblings. So the safe pattern is precise:

Connect the single database or parent page the agent needs. Open the target page, use the connection menu, and add your integration. If the agent should read a project database and nothing else, connect only that database. Do not connect a top-level page that contains half your workspace, because everything beneath it becomes visible.

Keep an allow-list in your tool layer too. Even with sharing scoped correctly, maintain an explicit list of the page and database IDs the agent may touch, and reject any ID that is not on it. This double layer protects against two mistakes: a teammate who connects the integration to an extra page, and an agent that infers a page ID it was never meant to use. The pattern mirrors the channel allow-listing in connecting an agent to Slack.

Reading and writing content

Notion's data model is worth understanding before your agent reads or writes, because it is not a flat document store. A workspace holds pages; pages are made of blocks (paragraphs, headings, to-dos, and so on); and a database is a special page whose rows are themselves pages with typed properties. Three consequences follow for an agent.

Reading a page is two moves, not one. Retrieving a page returns its properties, but its text lives in child blocks that you fetch separately, and those blocks can nest. An agent that reads only the page object and expects the body will find it empty. For deep pages, walk the block children recursively.

Querying a database returns pages with properties. Use the database query endpoint with filters and sorts rather than reading everything and filtering in the agent; it is faster and cheaper on the rate limit. Map each Notion property type (title, select, date, relation, and the rest) deliberately, since they do not all serialize the same way.

Writing means constructing blocks or properties correctly. Creating a row means creating a page in the database with a properties object that matches the schema; adding text means appending block children. Validate against the database schema before writing so a mismatched property does not fail the whole call.

Rate limits and audit

Notion's API allows roughly three requests per second on average per integration, with short bursts tolerated, and returns HTTP 429 with a Retry-After header when you exceed it (Notion request limits, retrieved 2026-07-01). An agent that walks a large database naively will hit this quickly. Page through results using the returned start_cursor, honor Retry-After rather than retrying immediately, and add simple backoff. There are also size limits on request payloads and block depth, so chunk large writes.

For audit, mirror your own trail. Notion's own history shows edits in the UI, but for a production agent you want a record in your systems: timestamp, integration identifier, the page or database ID, the operation, and the result. That log survives Notion outages and lets you review exactly what the agent changed, which is the same discipline covered in agent trust models.

Common failure modes

Ignoring pagination. The single largest failure mode. Notion returns up to 100 items and a cursor for the rest; an agent that reads the first page silently drops the remainder of a big database. Mitigation: always loop on has_more and start_cursor until the results are exhausted.

Stale or archived page IDs. The agent references a page that was deleted or archived and the call fails, or it writes to an archived page and the change never appears. Mitigation: handle 404 and archived states explicitly, and re-resolve IDs rather than caching them forever.

Missing block content. Reading the page object but not its child blocks returns empty bodies. Mitigation: fetch block children and recurse into nested blocks.

Rate-limit collisions during bulk work. Fanning out many writes at once trips the 429 limit and sheds requests. Mitigation: queue writes, respect Retry-After, and back off. For a broader treatment, see agent failure modes.

Frequently asked questions

Should an AI agent use an internal or a public Notion integration?

Internal, unless the agent must serve many separate workspaces. An internal integration lives in your own workspace, uses a single secret token, and is the simplest safe setup. Choose a public OAuth integration only when you are building a product that connects to customers' own Notion workspaces, because it adds the full consent and token-management flow.

What capabilities should a Notion integration have?

Grant the least it needs. Notion integration capabilities are read content, update content, and insert content, plus optional comment and user-information capabilities. A summarizing or reporting agent often needs only read content. Add insert or update capability only when the agent genuinely writes back, and leave user email access off unless a feature requires it.

How do I limit which Notion pages an agent can see?

Notion integrations see nothing by default. They only access pages and databases you explicitly connect them to, and access flows down to child pages. So share the single database or parent page the agent needs and nothing above it. This page-level sharing is the main security control, and it is far tighter than a broad workspace grant.

What are the Notion API rate limits for an agent?

Notion's API allows roughly an average of three requests per second per integration, with short bursts tolerated. Over the limit returns HTTP 429 with a Retry-After header. An agent that walks a large database should page through results, respect Retry-After, and back off rather than retrying immediately, or it will be throttled and lose data silently.

What is the most common Notion agent failure mode?

Missing data because of pagination. Notion returns up to 100 results per request and a start_cursor for the rest; an agent that reads only the first page silently ignores everything after it. The second most common failure is a stale or archived page ID: the agent references a page that was deleted or archived and the call fails. Handle pagination fully and treat 404 and archived responses explicitly.

Three takeaways before you close this tab

Sources