> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Let AI Agents Search and Update Notion Pages

> Let agents search Notion, read pages, create notes, and query databases. Connect with OAuth, pick which pages to share, and keep tokens out of the agent.

## Overview

Buckle connects AI agents to Notion through Notion's OAuth flow. Agents can search your workspace, read page content, create and update pages, and query databases. The gateway injects OAuth credentials into requests to the Notion API automatically.

This is useful for agents that need to look up internal documentation, create tasks or notes, or sync data with Notion databases.

## What you will set up

* A Notion connection through OAuth, limited to the pages and databases you select
* Automatic token injection on Notion API requests
* Per-agent, per-tool access to your workspace

## Setup

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **Notion**.

**2. Authorize**

Click **Connect Notion**. You'll be redirected to Notion to authorize Buckle. Select which pages and databases the integration can access, then click **Allow access**.

![Buckle connect window for Notion on Cloud, showing the Connect to Notion button.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/notion/buckle-connect-notion.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=d47db98d20637adb84ef6069fb87fd7c)

The Notion connect window on Buckle Cloud.

## Self-hosted: use your own Notion integration

> [!NOTE]
>
> **Skip this section on Buckle Cloud.** It's only for self-hosted Buckle without `NOTION_CLIENT_ID` and `NOTION_CLIENT_SECRET` set, or if you want your own company name on Notion's consent screen.

> [accordion] 1. Create the Notion integration
>
> Go to [notion.so/profile/integrations](https://www.notion.so/profile/integrations) and select **New integration**. Name it `Buckle`, pick your workspace, set **Type** to **Public**, and save.

> [accordion] 2. Set the capabilities
>
> Open **Capabilities** and turn on the ones your agents need:
>
> | Capability | Why |
> | - | - |
> | **Read content** | Search and read pages and databases |
> | **Update content** and **Insert content** | Create and edit pages |
> | **Read comments** | Read page comments |
> | **Read user information without email addresses** | Show who wrote what |

> [accordion] 3. Add the redirect URI
>
> In Buckle, open **Settings** > **Apps** > **Notion** > **Custom credentials** and copy the **Redirect URI**. In Notion, open **Configuration** > **OAuth Domain & URIs**, paste it into **Redirect URIs**, and save.
>
> ![Buckle Custom credentials card for Notion with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/notion/buckle-custom-credentials-notion.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=10e35d8d9a6c30dcbedf258fc312683a)
>
> Copy the Redirect URI from Custom credentials in Buckle.
>
> ![Notion integration settings, OAuth domains and URIs section, with https://buckle.example.com/v1/apps/notion/callback in Redirect URIs.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/notion/02-provider-redirect.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=f4f187035881528167966ecb0b247703)
>
> Notion's OAuth domains & URIs section with the Buckle Redirect URI.

> [accordion] 4. Connect with your integration
>
> In Notion, open **Configuration** and copy the **OAuth Client ID** and **OAuth Client Secret**. Paste both into **Settings** > **Apps** > **Notion** > **Custom credentials**, select **Save credentials**, then **Connect** and allow access in Notion.
>
> ![Notion integration named Buckle, Configuration tab showing the OAuth Client ID, a hidden OAuth Client Secret, and the Authorization URL.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/notion/01-provider-setup.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=ebb4a78075c445388e1bf66ee0ace2b8)
>
> Your integration's Configuration tab in Notion: the OAuth Client ID and Client Secret.

## What agents can do

* Search across all accessible pages and databases by keyword
* Read the full content of a page (text, headings, lists, tables, callouts)
* Create new pages in a specified parent page or database
* Update existing page content (append blocks, modify properties)
* Query databases with filters and sorts (e.g., all tasks with status "In Progress")
* Create new entries in a database with specified property values
* Update database entry properties (status, assignee, dates, tags)
* Read database schema (property names, types, select options)
* Archive and restore pages
* Read and add comments on a page

## Controlling access

Access is per agent: [grant](/docs/guides/agent-access.md) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization [rules](/docs/guides/rules.md) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches Notion.

## FAQ

> [accordion] Which Notion pages can the agent see?
>
> Only the pages and databases you select when you authorize Buckle in Notion.

> [accordion] Does the agent see my Notion token?
>
> No. The token stays in Buckle, and the gateway adds it at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] Can an agent read Notion without writing?
>
> Yes. A read-only agent is a single [grant](/docs/guides/agent-access.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.