# Notion plugin

The Notion plugin lets a Vaubaan Gateway mission use Notion without handing the agent a credential. Read and edit the pages, page content, databases and comments of the Notion pages shared with an internal connection.

- Version: `0.1.0` (package `@vaubaan/plugin-notion`)
- Status: stable
- Health: not enough reports yet — [what this means](/plugins/health)
- Source: [plugins/notion](https://github.com/vaubaan/gateway/tree/main/plugins/notion), catalog [risk-catalog.yaml](https://github.com/vaubaan/gateway/blob/main/plugins/notion/src/risk-catalog.yaml) version 1 of 2026-10-16
- How to connect an account: [Connect Notion](/docs/providers/notion)
- How it is modelled: [handbook](https://github.com/vaubaan/gateway/blob/main/docs/handbook/providers/notion.md)

One account is one internal connection of a Notion workspace, connected with its token. One resource is one top-level page or database shared with that connection, with everything under it. Notion has no environments: moving a page to the trash and deleting a block ask first in the presets. Writes are sent silently, so Notion notifies nobody.

## Permissions

Each permission is a named risk of the plugin's catalog: a mission holds an explicit list of them, never "all". The severity is computed from the permission's six axes (undo, blast radius, data, cost, visible to, lasts); nothing is decided from it.

| Permission | What it allows | Severity | Why it is a risk |
| --- | --- | --- | --- |
| `notion.read-content` | Read pages, their content and database descriptions | low | Page titles, properties and block content of the selected pages and databases, search results within them, and the description of their databases. Content written by people, which can carry instructions aimed at the agent. |
| `notion.query-databases` | Query database entries in bulk | medium | One query returns up to a hundred entries with all their properties — a CRM, a hiring pipeline or a task list in a few calls. Kept apart from reading one page so a mission can read documents without exporting tables. |
| `notion.read-comments` | Read comments and discussions | low | Open discussions on pages and blocks, with the names of who wrote them. Often more candid than the page itself. |
| `notion.page-create` | Create a page under a page | medium | Adds a page, with its first content, under an existing page of the selected roots. Additive and visible to everyone who can see the parent page; removed by moving it to the trash. |
| `notion.page-update` | Change a page's title, icon or cover | medium | Overwrites what a page is called and how it looks. The previous value is kept only in Notion's page history, whose length depends on the workspace's plan. |
| `notion.content-append` | Add content to a page | medium | Adds blocks (text, lists, to-dos, code, links) at the start or the end of a page or a block, or after a given block. Nothing existing is changed. |
| `notion.block-update` | Rewrite a block of a page | medium | Replaces the content of one existing block — a paragraph, a heading, a to-do, a line of a table — with new text. What people wrote there is kept only in Notion's page history, and a mention in the new text can notify the person it names. |
| `notion.block-delete` | Delete a block of a page | medium | Moves one block of a page, and the blocks nested in it, to Notion's trash: it disappears for everyone. It can be restored in Notion, not by the agent. Never a page or a database, and never a block that holds one: moving a page to the trash is its own permission. A synced block deleted at its original also disappears wherever it is copied. |
| `notion.page-trash` | Move a page to the trash | high | The page and everything under it — sub-pages, inline databases — disappear for everyone. It can be restored from Notion's trash; the API cannot delete it for good. Database entries are pages too. |
| `notion.page-restore` | Bring a page back from the trash | high | A page someone moved to the trash — out of date, wrong or confidential — reappears with everything under it for everyone who can see where it was. It can be moved to the trash again, but whoever saw it in between has seen it. |
| `notion.root-trash` | Move a whole shared root page to the trash | high | Trashing the page that was shared with the connection takes the whole resource away: every page under it, for every person and every mission. Listed in no preset; a mission that needs it holds it explicitly, beside the permission to trash a page. |
| `notion.entry-create` | Add an entry to a database | medium | Creates a row in a database: a task, a contact, a ticket. Can start the database's automations, which run whatever the notifications. |
| `notion.entry-update` | Change a database entry's properties | medium | Overwrites the values of an entry — a status, an owner, a date, a relation; a list value replaces the whole list. Views, automations and relations elsewhere follow the change; the previous value is only in the page history. |
| `notion.comment-create` | Add a comment | low | Opens a discussion on a page or a block, or replies to an open one, signed by the connection. Notifies the people it mentions: Notion offers no silent comment. |
| `notion.uncategorized-write` | Uncategorized Notion write | medium (the catch-all: touched only by a call no other permission covers) | Catch-all for writes without a dedicated entry. Seen in an audit, it means a tool classifies to a slice no entry covers: add the entry. |

## Presets

A preset pre-fills the permissions of a mission for one account, with a limit per period, a rate and whether each permission runs freely or asks the mission creator first. The person creating the mission adjusts it; the mission stores the explicit list.

### Read-only

`read-only` — Read the pages, databases and comments of the selected roots. No write, no comment.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `notion.read-content` | Read pages, their content and database descriptions | 3000 | 30 per minute | runs freely |
| `notion.query-databases` | Query database entries in bulk | 500 | 10 per minute | runs freely |
| `notion.read-comments` | Read comments and discussions | 500 | 10 per minute | runs freely |

### Reviewer

`reviewer` — Read everything in the selected roots and leave comments. No change to pages or databases.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `notion.read-content` | Read pages, their content and database descriptions | 3000 | 30 per minute | runs freely |
| `notion.query-databases` | Query database entries in bulk | 500 | 10 per minute | runs freely |
| `notion.read-comments` | Read comments and discussions | 500 | 10 per minute | runs freely |
| `notion.comment-create` | Add a comment | 100 | 5 per minute | runs freely |

### Editor

`editor` — Daily work: read, comment, create and edit pages, their content and database entries freely; moving a page to the trash and deleting a block ask first. Never trashes a whole root.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `notion.read-content` | Read pages, their content and database descriptions | 5000 | 30 per minute | runs freely |
| `notion.query-databases` | Query database entries in bulk | 1000 | 10 per minute | runs freely |
| `notion.read-comments` | Read comments and discussions | 1000 | 10 per minute | runs freely |
| `notion.comment-create` | Add a comment | 200 | 5 per minute | runs freely |
| `notion.page-create` | Create a page under a page | 200 | 10 per minute | runs freely |
| `notion.page-update` | Change a page's title, icon or cover | 300 | 10 per minute | runs freely |
| `notion.content-append` | Add content to a page | 500 | 15 per minute | runs freely |
| `notion.block-update` | Rewrite a block of a page | 300 | 10 per minute | runs freely |
| `notion.entry-create` | Add an entry to a database | 300 | 10 per minute | runs freely |
| `notion.entry-update` | Change a database entry's properties | 500 | 15 per minute | runs freely |
| `notion.page-restore` | Bring a page back from the trash | 20 | 2 per minute | runs freely |
| `notion.page-trash` | Move a page to the trash | 20 | 2 per minute | ask me first |
| `notion.block-delete` | Delete a block of a page | 50 | 5 per minute | ask me first |

## Tools

| Tool | What it does |
| --- | --- |
| `notion__list_roots` | List the shared roots |
| `notion__search_content` | Search pages and databases |
| `notion__get_page` | Read a page |
| `notion__list_block_children` | Read a page's content |
| `notion__get_database` | Read a database |
| `notion__get_data_source` | Read a database's schema |
| `notion__query_data_source` | Query a database |
| `notion__create_page` | Create a page |
| `notion__update_page` | Update a page |
| `notion__append_blocks` | Add content to a page |
| `notion__update_block` | Rewrite a block of a page |
| `notion__delete_block` | Delete a block of a page |
| `notion__trash_page` | Move a page to the trash |
| `notion__restore_page` | Bring a page back from the trash |
| `notion__create_entry` | Add a database entry |
| `notion__update_entry` | Update a database entry |
| `notion__list_comments` | Read comments |
| `notion__create_comment` | Add a comment |

## Health

Health: not enough reports yet. A plugin version is deemed validated by the community with at least 200 reports and 90 % of them successful, over the last 90 days, as reported by the instances whose operators turned community telemetry on. It is a community signal, not a security guarantee.