Notion Integration

Connect your Notion workspace so AI agents can search, read, create, and update pages and databases alongside your team.

Overview

The Notion Integration allows your AI agents to interact with your organization's Notion workspace through 7 schema-aware tools. Agents can search across pages and databases, query structured database entries, read and write page content, leave comments, and discover workspace members. The integration automatically discovers your workspace's actual database structures, property names, and select options so agents know exactly what is available.

Unlike read-only integrations, Notion tools support both reading and writing. Agents can create new pages and database entries, update properties, insert or replace content sections, and archive pages. Destructive operations like permanent deletion, schema modification, and page moves are excluded for safety.

info

The integration uses Notion's markdown content API, so agents read and write page content as natural markdown text rather than manipulating individual blocks.

Use Cases

• Project Management - Agent queries a Notion project tracker to find overdue tasks, summarizes status for the business owner, and creates new task entries when action items are identified from emails
• Knowledge Base - Agent searches the company's Notion wiki to find relevant documentation when answering questions, reads page content for context, and creates new pages to document decisions or meeting notes
• Collaboration - Agent leaves comments on Notion pages to provide updates, flag issues, or ask questions, making agent work visible within the team's existing Notion workflow
• CRM & Client Management - Agent queries a Notion client directory database to look up customer details, updates status fields after interactions, and creates follow-up task entries

How It Works

OAuth Connection          Schema Discovery          Agent Tools
        |                        |                       |
        v                        v                       v
+-----------------+       +-----------------+     +-----------------+
| Admin authorizes|  ->   | Auto-discover   | ->  | 7 tools created |
| via Notion      |       | databases,      |     | with schema-    |
| OAuth 2.0       |       | properties,     |     | enriched        |
|                 |       | users, options  |     | descriptions    |
+-----------------+       +-----------------+     +-----------------+

When you connect your Notion workspace via OAuth, the system automatically discovers your workspace's databases, property schemas, select options, and members. Seven tools are created with descriptions enriched by your actual data model so the LLM knows exactly what databases exist, what properties they have, and what values are valid.

Getting Started

Prerequisites

Before connecting Notion:

1. Pro Plus+ Subscription - The Notion integration requires the custom.notion feature code on your subscription
2. Notion Account - You need an active Notion workspace with the pages and databases you want agents to access
3. Notion Admin Access - You must be an admin on the Notion workspace to authorize the OAuth connection
4. Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration

Step 1: Navigate to Notion Connection

1. Go to Build > Connections > Notion
2. You will see the Notion integration page with a summary of capabilities

Step 2: Connect Notion

1. Click Connect Notion
2. An OAuth popup opens and redirects you to Notion's authorization page
3. Sign in to your Notion account if prompted
4. Select which pages and databases to share with the integration
5. Click Allow access to authorize the connection
6. The popup closes and your connection is established

tip

When selecting pages to share, choose the top-level pages that contain your databases and documentation. Child pages inherit sharing from their parents.

Step 3: Review Schema Discovery

After connecting, the system automatically discovers your workspace's data model:

• Databases with their property names and types
• Select and multi-select options for each property
• Workspace members available for assignments and mentions
• Database relationships and formula fields

Schema discovery runs automatically and typically completes within a few seconds. The schema is cached and refreshes automatically every 6 hours.

Step 4: Assign Tools to Agents

1. Go to Build > AI Agents > Agents
2. Edit the agent that should use Notion
3. In the Tools section, find the Notion tools
4. Enable the tools you want the agent to use
5. Save the agent

Managing Your Connection

Connection Details

Each connection displays:

Field	Description
Workspace Name	Your Notion workspace display name
Workspace ID	Unique Notion workspace identifier
Status	Current connection status (Active, Error, Token Expired)
Connected By	Email of the user who authorized the connection
Last Schema Sync	When the schema cache was last refreshed

Test Connection

Click Test Connection to verify the integration is working. The system confirms that the access token is valid and the Notion workspace is reachable.

Refresh Schema

Click Refresh Schema to manually trigger a fresh discovery of your workspace's databases, properties, and members. This is useful when you have made changes to your Notion workspace, such as adding new databases, creating custom properties, or changing select options.

Schema also refreshes automatically every 6 hours in the background without blocking tool execution.

Disconnect

To disconnect your Notion workspace:

1. Click the Disconnect button
2. Confirm the disconnection in the dialog

warning

Disconnecting removes all Notion tools and their agent assignments. Agents will no longer be able to access Notion data. You can reconnect at any time.

Schema Browser

The schema browser displays your workspace's data model so you can see exactly what your agents have access to.

Databases Tab

Shows all databases shared with the integration, including their properties and types. For example:

Project Tracker
 |- Name [title]
 |- Status [select: Not Started, In Progress, Done]
 |- Assignee [people]
 |- Due Date [date]
 |- Priority [select: P0, P1, P2]
 |- Tags [multi_select: Bug, Feature, Docs]

Meeting Notes
 |- Title [title]
 |- Date [date]
 |- Attendees [people]
 |- Type [select: Standup, Planning, Retro]

Agents use database names and property names directly in their queries, so any changes to your workspace should be followed by a schema refresh.

Property Types

The schema browser shows the type of each property, which determines how agents can filter and set values:

Property Type	Description	Example Values
title	Page title (every database has one)	"Implement authentication"
text	Rich text content	"Meeting notes for Q3"
number	Numeric values	42, 3.14
select	Single choice from options	"In Progress"
multi_select	Multiple choices from options	["Bug", "Feature"]
date	Date or date range	"2026-03-15"
people	Workspace members	"Jane Smith"
checkbox	Boolean value	true, false
url	Web address	"https://example.com"
email	Email address	"jane@example.com"
status	Status with groups	"In Progress" (group: Active)
relation	Link to another database	Related record ID

Users Tab

Lists all workspace members who can be referenced in people properties and mentions.

Available Tools

When you connect Notion, seven tools are automatically created and made available for agent assignment.

1. Notion Search (notion_search)

Search across pages and databases in the connected workspace by title.

Parameter	Type	Required	Description
query	string	Yes	Search text to match against page and database titles
filter_type	string	No	"page" or "database" to narrow results
sort_direction	string	No	"ascending" or "descending" by last edited time

Example use: "Find all pages related to Q3 planning"

2. Notion Query Database (notion_query_database)

Query a Notion database with structured filters and sorting to retrieve entries.

Parameter	Type	Required	Description
database_id	string	Yes	ID of the database to query (listed in schema)
filter	object	No	Notion filter object with property-based conditions
sorts	array	No	Sort criteria with property name and direction
page_size	number	No	Results per page (max 100, default 20)

Filter syntax:

{
  "and": [
    { "property": "Status", "select": { "equals": "In Progress" } },
    { "property": "Priority", "select": { "equals": "P1" } }
  ]
}

Example use: "Find all In Progress tasks assigned to Jane with P1 priority in the Project Tracker database"

tip

The tool description dynamically lists all available databases with their property names, types, and select options. Agents can see which databases exist and what filters are valid without any manual configuration.

3. Notion Read Page (notion_read_page)

Read a page's properties and full content as markdown.

Parameter	Type	Required	Description
page_id	string	Yes	ID of the page to read
include_content	boolean	No	Whether to fetch markdown content (default: true)

Returns the page title, properties, full markdown content, URL, and edit history. Content is truncated at approximately 30,000 characters with a note if the page is very large.

Example use: "Read the full content of the Q3 Planning page"

4. Notion Create Page (notion_create_page)

Create a new database entry or sub-page with properties and content.

Parameter	Type	Required	Description
parent_type	string	Yes	"database" (new entry) or "page" (sub-page)
parent_id	string	Yes	ID of the parent database or page
title	string	Yes	Page title
properties	object	No	Property values for database entries (e.g., { "Status": "Not Started" })
content	string	No	Markdown content for the page body
icon	string	No	Emoji icon for the page

Property values use a simplified format. The tool automatically converts { "Status": "Not Started" } to Notion's typed format based on the schema cache.

Example use: "Create a new task in the Project Tracker database titled 'Review Q3 metrics' with status Not Started and priority P1"

5. Notion Update Page (notion_update_page)

Update an existing page's properties, content, or archive status.

Parameter	Type	Required	Description
page_id	string	Yes	ID of the page to update
properties	object	No	Updated property values
content	string	No	Markdown content to insert or replace
content_action	string	No	"insert" (append, default) or "replace" (surgical replacement)
content_range	string	No	Ellipsis-based selector for replace (e.g., "start text...end text")
icon	string	No	Updated emoji icon
archived	boolean	No	Set true to move page to trash (soft delete)

Content updates use surgical replacement rather than full-page overwrite. The "replace" action targets a specific section of the page identified by the content range, leaving all other content untouched.

Example use: "Mark the 'Review Q3 metrics' task as Done and add a comment about the results"

6. Notion Manage Comments (notion_manage_comments)

List or create comments on a Notion page.

Parameter	Type	Required	Description
action	string	Yes	"list" or "create"
page_id	string	Yes	Page to list or create comments on
content	string	Conditional	Comment text (required for create)

Example use: "Leave a comment on the project status page noting that the deployment is complete"

7. Notion List Users (notion_list_users)

Discover workspace members for use in people property assignments and mentions.

Parameter	Type	Required	Description
page_size	number	No	Results per page (default: 100)

Returns user IDs, names, emails, and types (person or bot). Use this to look up user IDs before assigning people properties.

Example use: "List all workspace members to find Jane Smith's user ID for task assignment"

Authorization & Access Control

AICOS Authorization

All Notion tools require VIP authorization level in AICOS. This means:

• External senders cannot trigger any Notion tool
• Internal employees can trigger Notion tools if they hold VIP status
• Business owners and admin VIPs have full access

Personal Assistant Authorization

All Notion tools require internal user authorization in Personal Assistant. Only employees within the organization can use Notion tools through their PA.

Page-Level Access

The Notion integration can only access pages and databases that were explicitly shared during the OAuth authorization step. If an agent tries to access a page that was not shared, it receives a clear error message suggesting the admin share the page with the integration.

info

To expand what the integration can access, visit your Notion workspace settings and share additional pages with the Outermind integration. Then click Refresh Schema in Control Bridge to discover the newly shared databases.

Security & Limitations

Security

• OAuth 2.0 authorization - No Notion credentials stored in Outermind
• Encrypted token storage - Tokens encrypted with AES-256-CBC at rest
• Distributed refresh locking - Prevents token replay attacks across serverless instances
• Tenant isolation - Each tenant's Notion connection and tools are scoped to that tenant only
• Audit logging - Every tool execution is logged with the agent, parameters, and results

Safety Guardrails

• No schema modification - Agents cannot add, rename, or delete database properties
• No permanent deletion - Agents can only archive pages (soft delete via archived: true)
• No page moves - Agents cannot move pages between parents
• Surgical content updates - Content replacement targets specific sections, not entire pages
• No file uploads - Agents cannot attach files to Notion pages

Rate Limits

The Notion API enforces rate limits that apply to your connection:

Limit	Value	Scope
Per-second	3 requests/second	Per integration

If an agent hits a rate limit, the tool automatically retries with exponential backoff up to 3 times, respecting the Retry-After header from Notion.

Limitations

• Single workspace - Only one Notion workspace per Control Bridge tenant
• Shared pages only - The integration can only access pages explicitly shared during OAuth setup
• Content truncation - Very large pages (over ~30,000 characters) are truncated
• No block-level editing - Content is read and written as markdown, not individual blocks
• No file attachments - Cannot upload or download files attached to Notion pages
• Select option limits - Schema enrichment shows the first 20 options per select/multi-select property

Troubleshooting

OAuth Connection Fails

Problem: Authorization fails or the popup does not complete

Solutions:

1. Ensure you are signed in to Notion as a workspace admin before clicking Connect
2. Verify your browser allows popups from the Notion domain
3. Check that your Notion workspace is active and accessible
4. Try a different browser or incognito window if the issue persists

Agent Receives "Page Not Shared" Error

Problem: Agent tries to access a page or database and gets a 403 error

Solutions:

1. Open your Notion workspace and find the page or database
2. Click the "..." menu and select "Add connections"
3. Search for and select the Outermind integration
4. Return to Build > Connections > Notion and click Refresh Schema
5. Retry the agent execution

Schema Not Showing New Databases

Problem: Recently created databases do not appear in the schema browser

Solutions:

1. Verify the database's parent page is shared with the Outermind integration
2. Click Refresh Schema to trigger a fresh discovery
3. If the database was just created, wait a moment and refresh again
4. Check that the database is not in a private page that has not been shared

Agent Cannot Find Notion Tools

Problem: Notion tools do not appear when editing an agent

Solutions:

1. Verify the Notion connection is active at Build > Connections > Notion
2. Confirm the connection status shows "Active"
3. Refresh the page
4. If you recently connected, wait a moment for tool creation to complete

Token Expired

Problem: Notion tools return authentication errors

Solutions:

1. Token refresh is automatic; wait a moment and retry
2. If the refresh fails, navigate to Build > Connections > Notion and check the connection status
3. If status shows an error, click Disconnect and reconnect via OAuth

Agent Returns Incorrect Database Results

Problem: Query returns unexpected or empty results

Solutions:

1. Verify the database ID is correct by checking the schema browser
2. Ensure filter property names match exactly (property names are case-sensitive)
3. For select properties, verify the option value matches an existing option in the schema
4. Test the same query directly in Notion to confirm data exists
5. Click Refresh Schema if you recently changed property options

Best Practices

Agent Instructions

Help your agents use Notion effectively by including guidance in their instructions:

When working with Notion:
1. Use notion_search to find pages and databases by title
2. Use notion_query_database with filters to find specific entries
3. Use notion_read_page to get full page content before making updates
4. When creating database entries, check the available properties first
5. For content updates, use the replace action with a content range
   to update specific sections rather than inserting at the end
6. Use notion_list_users to look up user IDs before assigning people

Schema Refresh

• Refresh schema after adding new databases or properties in Notion
• Refresh schema after changing select or multi-select options
• Schema refreshes automatically every 6 hours, but manual refresh gives you immediate visibility
• Background refresh does not block tool execution (agents use the cached schema)

Tool Assignment Strategy

• Read-only agents - Enable notion_search, notion_query_database, and notion_read_page for research and lookups
• Operations agents - Enable all seven tools for full workspace interaction
• Collaboration agents - Add notion_manage_comments for visible collaboration within Notion
• Start with read-only tools and add write tools (notion_create_page, notion_update_page) as needed

Page Sharing

• Share top-level workspace pages to give agents broad access
• For more restricted access, share only specific databases and pages
• Review shared pages periodically to ensure agents have access to current resources
• Child pages inherit sharing from their parents in Notion

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• Agent Executions - View tool execution logs
• HubSpot CRM Integration - Similar schema-aware integration for HubSpot
• Xero Accounting Integration - Read-only accounting integration