Read, edit, and query Notion from Guild agents

Integrations · Notion

A Guild agent can read, write, and query your Notion workspace on your team’s behalf. Guild stores the OAuth credential server-side and injects it into every request, so agent code never handles a token. Credential policies let you restrict exactly which operations each agent may perform, and every call appears in the audit record.

Book a demo

See how teams govern agents that use Notion.

Start free

Connect Notion and scope your first agent.

What the Notion integration exposes

The integration provides tools that cover pages, blocks, databases, data sources, comments, users, and file uploads. Agents can search by title, render pages as Markdown, query and update database rows, create and move pages, manage blocks, and upload files. Search matches titles only, not page body content. The notion_oauth_retrieve_page_markdown tool may truncate long pages; check its truncated field.

How it works

Connect your Notion account

In Guild, go to Access & setup > Credentials, click Connect, and select notion-oauth. See Credentials for workspace, member, and agent-scoped options.

Choose which pages to share

Sign in to Notion, pick the workspace, and select the pages Guild can access. The agent can reach only those pages and anything under them.

Import tools into your agent

Import NotionOauthTools from the guildai~notion-oauth package and spread it into your agent’s tools object. Use pick() from the Agent SDK to include only the tools your agent needs.

Why Notion access needs governing

Guild’s credential proxy enforces credential policies before any request leaves the platform. You can write ALLOW and DENY rules scoped to specific operations, agents, or workspaces, so a read-only wiki agent cannot edit or delete pages even if the underlying credential permits it. Credentials are stored and injected server-side, so agent code, prompts, and containers never see the OAuth token. You can scope a credential to a single agent, a single workspace, or a single member using the options on the Credentials page. A team that shares one Notion connection can still give each agent a separate policy.

About the Notion integration

The Notion integration connects agents to a Notion workspace with OAuth. Agents can search, read pages as Markdown, query and update databases, create and edit pages and blocks, comment, and upload files. The integration is guildai~notion-oauth.

The older guildai~notion package is retired, and agents that import notionTools from it get errors. Use guildai~notion-oauth instead.

Authentication

Type: OAuth 2.0

When you connect, Notion asks which pages to share with Guild. The agent can reach only those pages and the pages and databases under them. To give it more later, share additional pages with the connection in Notion.

Setup

Connect Notion

In Guild, go to Access & setup > Credentials, click Connect, and select notion-oauth.

Choose pages

See Credentials for workspace, member, and agent-scoped credentials.

Usage

import { NotionOauthTools } from "@guildai-services/guildai~notion-oauth"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that answers questions from our Notion wiki",
  tools: { ...NotionOauthTools },
})

Selecting specific tools

Tools are named with the notion_oauth_ prefix. Use pick() to include only what your agent needs.

import { NotionOauthTools } from "@guildai-services/guildai~notion-oauth"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that finds and reads Notion pages",
  tools: {
    ...pick(NotionOauthTools, [
      "notion_oauth_search",
      "notion_oauth_retrieve_page_markdown",
      "notion_oauth_query_data_source",
    ]),
  },
})

notion_oauth_search matches page and data source titles only, not page content. Search results include data source IDs you can pass to notion_oauth_query_data_source. If you have a database ID instead, get its data sources with notion_oauth_retrieve_database first.

Tools

Tools in the latest published version of guildai~notion-oauth:

All 33 tools

Tool	What it does
`notion_oauth_append_block_children`	Adds children to the end of a block or page by default.
`notion_oauth_complete_file_upload`	Call after every part has been sent.
`notion_oauth_create_comment`	Exactly one target: `parent.page_id`, `parent.block_id`, or `discussion_id` to reply in an existing thread.
`notion_oauth_create_database`	Creates a database under a page or at the workspace root.
`notion_oauth_create_data_source`	Create data source.
`notion_oauth_create_file_upload`	Step one of attaching a file.
`notion_oauth_create_page`	Creates a page under a page, a data source, or the workspace root.
`notion_oauth_delete_block`	Delete block.
`notion_oauth_delete_comment`	A connection may only delete comments it created; anything else returns 404.
`notion_oauth_list_comments`	List comments.
`notion_oauth_list_file_uploads`	List file uploads.
`notion_oauth_list_users`	Returns members and bots in the workspace.
`notion_oauth_move_page`	Move page.
`notion_oauth_query_data_source`	Lists the pages (rows) of a data source, optionally filtered and sorted.
`notion_oauth_retrieve_block`	Returns a single block.
`notion_oauth_retrieve_block_children`	Returns only the first level of children.
`notion_oauth_retrieve_bot_user`	Returns the bot user for the current token, including the workspace it belongs to.
`notion_oauth_retrieve_comment`	Retrieve comment.
`notion_oauth_retrieve_database`	Returns the database’s metadata and its `data_sources` array.
`notion_oauth_retrieve_data_source`	Returns the `properties` schema — the property names, IDs and types of every column.
`notion_oauth_retrieve_file_upload`	Poll this to watch `status` move from `pending` to `uploaded`, and to read `file_import_result` for an `external_url` import.
`notion_oauth_retrieve_page`	Returns the page’s properties, not its content.
`notion_oauth_retrieve_page_markdown`	Renders the whole page as Notion-flavored Markdown in one call.
`notion_oauth_retrieve_page_property_item`	Returns one property’s value.
`notion_oauth_retrieve_user`	Retrieve user.
`notion_oauth_search`	Searches every page and data source the integration has access to, matching against the title only (not body content).
`notion_oauth_send_file_upload`	Uploads the file contents as `multipart/form-data`.
`notion_oauth_update_block`	Replaces the content of one block.
`notion_oauth_update_comment`	A connection may only update comments it created; anything else returns 404.
`notion_oauth_update_database`	Edits container-level attributes only.
`notion_oauth_update_data_source`	Keys of `properties` are the existing property names or IDs; a null value removes the property, a new key adds one.
`notion_oauth_update_page`	Updates the properties of an existing page.
`notion_oauth_update_page_markdown`	Edits page content without dealing in block objects.

Limitations

notion_oauth_retrieve_page_markdown cuts off long pages. Check its truncated field.

Frequently asked questions

Can an agent reach pages I did not select during setup?

No. When you connect, Notion limits the agent to the pages you chose and the pages under them. To grant access to more pages, share additional pages with the connection in Notion.

Can the agent search inside the body of a page?

Not yet. The notion_oauth_search tool matches against titles only, not page body content.

How do I stop one agent from editing pages while another can?

Write a credential policy that denies mutating operations for the read-only agent. DENY rules are enforced by Guild’s credential proxy before the request reaches Notion, and a DENY always wins over an ALLOW.

Does the integration support webhook events from Notion?

No. The catalog entry for guildai~notion-oauth lists no webhook events, so agents cannot trigger on Notion activity through this integration.

Put a governed agent on Notion this week

Book a demo

See how teams govern agents that use Notion.

Start free

Connect Notion and scope your first agent.

Also runs on Guild: Google Docs · Google Drive · Google Sheets · Google Slides Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Read, edit, and query Notion from Guild agents

Book a demo

Start free

What the Notion integration exposes

How it works

Why Notion access needs governing

About the Notion integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Limitations

Frequently asked questions

Put a governed agent on Notion this week

Book a demo

Start free

Book a demo

Start free

​What the Notion integration exposes

​How it works

​Why Notion access needs governing

​About the Notion integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Limitations

​Frequently asked questions

​Put a governed agent on Notion this week

Book a demo

Start free

​Related

What the Notion integration exposes

How it works

Why Notion access needs governing

About the Notion integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Limitations

Frequently asked questions

Put a governed agent on Notion this week

Related