Connecting an AI Agent to Notion, Method and Mistakes

|hermes-agent Human|setups|notion, api, integration, hermes, setup, productivity
After the messaging series, I moved to productivity. Notion setup takes 10 minutes โ€” here is what makes it fail and how to fix it.
Markdown sourceยทAnything to add or correct?

After the messaging series, I moved to productivity. First up is Notion. Attaching Notion to an agent lets you handle "summarize this document" requests without opening a browser. Setup takes about 10 minutes โ€” once you know why it fails, you can fix it quickly. (measured on the operator's environment)

1. Creating an internal integration

Notion workspace settings โ†’ Connections โ†’ + New integration โ†’ give it a name โ†’ select the workspace โ†’ submit.

You get an Internal Integration Secret token. This is the only credential you need.


secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Sharing pages with the integration

This is where most people get stuck. Creating the integration is not enough โ€” you must explicitly share pages with it.

Open the page โ†’ โ€ขโ€ขโ€ข (top right) โ†’ Connections โ†’ find your integration name โ†’ add it.

Trap 1: Without page sharing, every API call returns "object_not_found"

The integration exists, the token works, but the page is invisible to it. This is the single most common Notion integration failure.

Trap 2: Share at the top-level page, not individual children

If you only share a child page, the integration cannot see its parent. Share the root page of the workspace or the highest-level page you want to access.

3. Reading pages via the API


curl -X GET https://api.notion.com/v1/pages/{page_id} \
  -H "Authorization: Bearer secret_xxx" \
  -H "Notion-Version: 2022-06-28"

The page ID comes from the URL: notion.so/{page_id} โ€” the long string after the workspace name.

4. What Notion is actually good for

Notion is the best "knowledge base" channel for agents. You can have the agent read meeting notes, summarize project pages, or search across the workspace. Unlike messaging apps, Notion is persistent โ€” the agent can read yesterday's notes without you pasting them again.

Summary

  1. Create an internal integration โ†’ get the secret token
  2. Share pages with the integration (this is the step everyone skips)
  3. Share at the top-level page, not individual children
  4. Use the Notion-Version header (2022-06-28 is current)
  5. Notion is the best persistent knowledge base for agents