An AI agent that can read and write to your Notion workspace is one of the most useful things you can build without code. Think: an agent that reads new rows in a Notion database, summarizes them, and writes the summary back. Or a Telegram bot that drops meeting notes straight into a Notion page. The hard part is almost never the AI — it’s the connection. Beginners get stuck on one specific step (granting the integration access to the actual page), and everything fails silently until they fix it. This guide walks the whole path, in order, so it works the first time.
What you actually need to connect
There are three moving parts, and it helps to name them before you start clicking:
- The Notion integration (a “connection”) — a small piece of access you create inside Notion. It gives you a secret token that proves “this app is allowed to talk to my workspace.”
- The page or database you want the agent to touch. Critically, the integration does not get access to your whole workspace automatically. You share specific pages with it, one by one (or share a parent page so its children are included).
- The no-code platform running your agent — Make, Zapier, n8n, or similar. This is where the AI logic lives and where you paste the token.
Miss the middle one and you’ll see errors like “object not found” or an empty result even though your token is valid. That’s the number-one cause of “my Notion agent doesn’t work.”
Step 1: Create the Notion integration and get your token
Go to notion.so/my-integrations and click New integration. You’ll choose:
- Name — call it something you’ll recognize later, like “Make – CRM agent.” Future-you will thank you when you have five of these.
- Associated workspace — pick the workspace that holds the pages you want to automate. An integration is locked to one workspace.
- Type: Internal — choose this. Internal integrations use a single, non-expiring token and are exactly right for your own automations. (Public integrations are only needed if you’re shipping an app that other Notion users install via OAuth. For a personal or team agent, internal is simpler and correct.)
After saving, open the integration and find the Internal Integration Secret. Click Show, then copy it. Modern Notion tokens start with ntn_ (older ones started with secret_ — both work, but new ones you create now will be ntn_). Treat this string like a password: anyone with it can read and edit every page you’ve shared with the integration.
Set the right capabilities
In the integration’s Capabilities settings, you’ll see Read content, Update content, and Insert content. Pick only what your agent needs. An agent that just reads a database to summarize it needs only Read. An agent that writes results back needs Read + Update (and Insert if it creates new pages/rows). Tighter capabilities = less damage if the token ever leaks. There’s also a “Read user information” toggle — leave it off unless you specifically need names/emails.
Step 2: Share the page or database with your integration (the step everyone skips)
This is the one that breaks people. Open the Notion page or database you want the agent to access. Click the ••• menu in the top-right corner, scroll down to Connections (or Add connections), and select the integration you just created. Confirm the access prompt.
A few things worth knowing:
- Access is inherited. Connect the integration to a parent page, and every sub-page and database inside it is included. So a clean trick is to put everything your agent needs under one parent page and connect once.
- For databases, connect the database itself, not just a single row. Open the full-page database view, then use its
•••menu. - You can revoke anytime from the same menu by hovering the connection and pressing Disconnect. Good for offboarding an agent.
If you ever get a “could not find database with ID” error later, 90% of the time it’s because the integration was never connected to that specific page. Come back here first.
Step 3: Get the database or page ID
Your no-code platform needs to know which database to act on. The ID is hidden in the URL. Open the database as a full page and look at the address bar:
notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...
That 32-character string before the ?v= is the database ID. (Some tools want it with dashes in UUID format — most no-code Notion modules accept it either way and handle the formatting for you.) Page IDs work the same way: it’s the long string at the end of a page URL.
Good news: in Make, Zapier, and n8n you usually don’t have to copy the ID by hand. Once the connection is authenticated, those tools show a dropdown of your shared databases. The ID still matters for debugging and for HTTP-module calls, so it’s worth knowing where it lives.
Step 4: Connect Notion inside your no-code platform
Here the path splits slightly by tool, but the shape is identical: add a Notion module/node, create a new connection, paste the token (or click through OAuth), then pick your database from the dropdown.
- Make — Add a Notion module, create a connection, and choose Internal connection type to paste your
ntn_token directly. Make’s modules (“Search Objects in a Database,” “Create a Database Item,” “Update a Database Item”) map cleanly to Notion’s read/insert/update. This is the most beginner-friendly visual route. - Zapier — Add a Notion app step and authorize via the popup. Zapier handles auth for you (no manual token paste) and is the fastest to a working flow. Watch its task-based pricing: every step in every run counts as a task, so a chatty agent gets expensive.
- n8n — Add a Notion node and create a credential of type Notion API, pasting your token. n8n is the strongest choice if the “agent” part is real — its AI Agent and Tool nodes let the model decide when to query or write Notion, with one execution covering the whole multi-step run.
Which platform fits which job
| Platform | Best for | Notion auth | Honest caveat |
|---|---|---|---|
| Make | Visual multi-step flows, tight budgets | Paste token (internal) | Steeper learning curve than Zapier for true beginners |
| Zapier | Fastest setup, huge app library | OAuth popup | Per-task pricing punishes complex/looping agents |
| n8n | Real agentic AI, self-hosting, complex logic | Paste token (credential) | Overkill for a simple “new row → Slack” trigger; needs more comfort with the canvas |
If your task is a straight-line automation (“new Notion row, send an email”), don’t reach for an AI agent at all — a plain Make scenario or Zap is cheaper, faster, and won’t hallucinate. Reserve the AI agent for when the model needs to decide something: which database to write to, how to categorize an entry, what to summarize.
Step 5: Test with a read before you ever write
Always prove the connection with a harmless read first. In Make, run a single “Search Objects in a Database” with a low limit. In n8n, run a “Get All” on the database. If rows come back, your token, connection, and ID are all correct — the foundation is solid. Only then wire up the write or update step. Testing write-first on real data is how people accidentally overwrite a live database.
When you connect the AI to it, give the agent explicit instructions about which database it owns and what fields exist, because the model can’t see your Notion schema unless you tell it. A short system prompt like “You manage the ‘Leads’ database. Properties: Name (title), Status (select: New/Contacted/Won), Notes (text). Only ever update the Status and Notes fields” prevents most garbage writes.
Common errors and what they actually mean
- “Could not find database / object not found” — the integration isn’t connected to that page. Go back to Step 2.
- “Unauthorized” / 401 — wrong or expired token, or you pasted it with a trailing space. Re-copy from my-integrations.
- “Validation error” on a property — you’re writing to a field name or type that doesn’t match (e.g., sending plain text to a Select field). Match Notion’s exact property names and types.
- Silent rate limiting — Notion’s API allows roughly 3 requests per second. An agent looping over hundreds of rows will hit this; add a small delay or batch your operations.
FAQ
Do I need a paid Notion plan to use the API?
No. The Notion API and internal integrations are available on the free plan. You can build and run a fully working AI agent against Notion without paying Notion a cent. Your cost, if any, comes from the no-code platform (Make/Zapier operations or tasks) and the AI model’s usage — not from Notion itself.
Is it safe to paste my Notion token into Make or n8n?
It’s reasonable, with sane precautions. Store the token in the platform’s credential/connection manager (never hard-code it into a text field or share it in screenshots). Scope the integration to only the capabilities and pages it needs, so a leak can’t touch your whole workspace. If you self-host n8n, the token stays on your own server, which is the most private option. And if a token is ever exposed, you can disconnect the integration from your pages instantly.
Can the agent create new pages, not just edit a database?
Yes — as long as the integration has the Insert content capability and is connected to a parent page where the new page should live. The agent can create database rows, create sub-pages, and append blocks (paragraphs, to-dos, headings) to existing pages. It cannot create things in areas you haven’t shared with it, which is the safety boundary working as intended.
Next step
Build the smallest possible version first: one integration, one database, one read. Get rows showing up in your no-code tool with zero AI involved. Once that’s solid, add a single AI step — for example, “read the latest row, write a one-sentence summary back into a Summary field.” That tiny working loop is the hard 80%; from there you can layer on triggers, more databases, and real agent decision-making with confidence that the Notion plumbing is correct.