Notion

​

What It Does

• One authorization, one workspace. The Notion workspace id becomes the connection’s providerAccountId and the workspace name its accountLabel. A second workspace is a second connection — see Multiple workspaces.
• Nothing syncs until you pick roots. Ingesting a whole workspace costs LLM tokens, so a fresh connection holds an empty selection and “everything” is not a valid selection.
• Manual sync. Notion sends no webhooks on this path, so /sync is what updates memory. Each run is incremental and forgets pages that were deleted or moved out of a selected root, as described for the dlt Notion connector.
• No extra to install. The adapter and notion_source() both use core dependencies.

​

Setup

​

1. Create the Notion public integration

​

2. Configure Cognee

​

3. Connect

# Mint the authorize URL (authenticated as the Cognee user who will own the data)
curl -X POST https://<your-host>/api/v1/integrations/notion/authorize \
  -H "Authorization: Bearer <your-cognee-token>"
# {"authorizeUrl":"https://api.notion.com/v1/oauth/authorize?...&owner=user&state=..."}

​

Choosing What to Index

curl https://<your-host>/api/v1/integrations/notion/resources \
  -H "Authorization: Bearer <your-cognee-token>"

{
  "id": "page:1f2e3d4c5b6a79881f2e3d4c5b6a7988",
  "name": "Engineering Wiki",
  "description": null,
  "attributes": {"kind": "page", "parent_kind": "workspace", "parent_id": null},
  "selected": false
}

curl -X PUT https://<your-host>/api/v1/integrations/notion/resources \
  -H "Authorization: Bearer <your-cognee-token>" \
  -H "Content-Type: application/json" \
  -d '{"resourceIds": ["page:1f2e3d4c5b6a79881f2e3d4c5b6a7988"]}'

​

Syncing and Status

curl -X POST https://<your-host>/api/v1/integrations/notion/sync \
  -H "Authorization: Bearer <your-cognee-token>"
# {"accepted": true}

1. Checks the token with GET /users/me. If Notion answers 401 / unauthorized, the connection is revoked locally and the sync stops. Because Notion usually issues tokens with no expiry, this is the only way a workspace that removed the integration in Notion shows up in Cognee.
2. Drops nested roots. A selected root that sits under another selected root would be read twice, under two node sets. The sync follows each root’s parent chain, one request per level, and drops it if the chain reaches another selected root. This also catches pages the picker could not hide, such as a page inside a toggle or column block of a shared page. If Notion reports an object on the chain as not shared, the root is kept. Any other lookup error stops the sync, so a flaky lookup never changes what is synced.
3. Runs one notion_source() per root through remember() with write_disposition="merge" and self_improvement=False. How the walk, rendering, deletions and node sets work, and what it costs, is described in the dlt Notion connector section.

import cognee

results = await cognee.recall(
    "What is our on-call rotation?",
    datasets=["notion_account_3f2a1b9c4d"],
)

​

Multiple Workspaces

curl https://<your-host>/api/v1/integrations/notion/connections \
  -H "Authorization: Bearer <your-cognee-token>"
# {"connections": [{"providerAccountId": "<workspace id>", "accountLabel": "Acme", "connectedAt": "..."}, ...]}

curl -X POST "https://<your-host>/api/v1/integrations/notion/sync?account_id=<workspace id>" \
  -H "Authorization: Bearer <your-cognee-token>"

​

Token Lifecycle

• No expiry, no refresh. When Notion’s token response carries no expires_in, the token is stored without an expiry and used as is. The token check at the start of each sync is what catches a revoked one.
• With an expiry, the access token is refreshed 5 minutes before it expires. Notion rotates the refresh token on every refresh, so refreshes for one workspace run one at a time within a process, and a compare-and-swap on the stored credential covers several processes. If a refresh response carries no new refresh token, the old one is kept.
• invalid_grant on refresh means the workspace removed Cognee’s access in Notion. The local connection is revoked; reconnect to fix it.
• A connection with no refresh token cannot refresh and has to reconnect.

​

Disconnect

# Revoke the connection, keep the indexed data
curl -X DELETE "https://<your-host>/api/v1/integrations/notion/connection" \
  -H "Authorization: Bearer <your-cognee-token>"

# Revoke it and forget the workspace's dataset as well
curl -X DELETE "https://<your-host>/api/v1/integrations/notion/connection?delete_data=true" \
  -H "Authorization: Bearer <your-cognee-token>"

​

Limitations

• No automatic refresh. No webhooks and no scheduler: /sync is the only thing that updates memory.
• Shared content only. The picker and the sync see only what the workspace shared with the integration.
• A workspace belongs to one Cognee user. Connecting a workspace another user holds ends in error_already_connected.
• The notion_source() limits apply, including the request cost of re-walking every root on each run and the 10,000-row cap on a data source. See the dlt Notion connector.
• One sync per workspace at a time, per process. The running-sync guard lives in the API process.

​

Troubleshooting

​

Related