Notion
Company documents · publisher buff · version 1.1.0
Notion pages and databases as context for answers — and questions right in the page discussion. The research report comes back as a page.
An answer in Buff relies on a task database in Notion — with the names of the database and its entries. The setup form: the address, the root pages and databases, and the integration token. The connection is live: eight tools, six of which only read (green). The connection check names the workspace, the integration and how many of the selected pages it can access. What the integration will get is written on its card in the connector’s catalogue.
Click a screenshot to open it in full. All screenshots are from a working installation.
Overview
In Notion the team keeps what is neither in the task nor in the code: requirements, decisions, procedures, runbooks — and the tables in which it tracks tasks and registers. The integration lets Buff read the pages and databases of the selected sections when an answer needs them, takes questions right in page comments and can leave the result as a page: the research report appears as a child page under the one where the question was asked.
Use cases
The situations it is installed for.
A sales manager checks the discount policy
A customer asks for a 20% discount. Who approves it and on what terms is written on the “Discount policy” page in Notion, not in the head of a manager who joined a month ago.
Result. The AI agent finds the page by its title, reads it and answers by it: up to 15% the manager decides alone, above that the head of department, and only with annual payment. With a link to the source.
A register where everything is written down
The product manager keeps agreements with customers in a Notion database: a row per customer, properties for what was promised, the deadline and the owner. Nobody retells that table when asking “what did we promise Romashka?”.
Result. The AI agent reads the database structure, filters the entries by the property needed and answers from the table rows — each property as text, the way a person sees it.
A question right on the page
Someone reads a procedure and does not understand how it applies to their case. Going to another tool for a question is an extra step people usually skip.
Result. They write to the bot in a page comment. The answer arrives in the same discussion thread and stays next to the text the question was about.
Research stays in Notion
You need to find out why the export breaks on Cyrillic and leave the analysis where the team will find it six months later — not in a chat thread.
Result. A `/research` request in a comment produces a child page with the report — the text itself, not a picture of text — and a PDF on it; a link arrives in the thread.
Examples
What to write and what comes back. How the bot is addressed is set in the connection settings — here it is “@buff”.
@buff what is our migration scheme called?
a comment on any page of a selected section
tool:
search_pages + get_pageThe migration scheme’s internal name is “Tobolsk”: the number is built as YY.MM.N. Source: the “Release procedure” page, “Migration scheme” section.
@buff which export tasks are in progress?
a question in the Buff app or a comment on the page
tool:
get_database + query_databaseThe “Tasks” database has two entries about export; one is in progress — “CSV export”, estimate 3, status “In progress”. The second, “Export encoding”, is already done. Links to the entries are below.
/research why the export breaks on Cyrillic
a comment on the procedure page
tool:
get_page + create_pageThe word after the mention picks the work: without it — a short answer, “research” — research, “task” — a draft task. The research report will appear as a child page under this one, with a PDF; a link will arrive in the thread.
@buff what does this section say about backups?
a comment on the section’s parent page
tool:
get_page_childrenThe section has four nested pages; two are about backups: “Backup” (the schedule, the retention period) and “Restore” (the procedure and who approves it). Both are linked.
What it does
Reads what it needs, when it needs it
search_pages searches titles through Notion and the text of the pages in scope on its own — Notion itself searches only titles, and a question is usually about what is written on the page. get_page returns a whole page together with its discussion, get_page_children what is nested in it, get_database and query_database a database’s structure and its entries. The model calls them itself when a question requires it: nothing is copied to us in advance or indexed, and you pay for what is actually read.
A page arrives as markdown
Notion returns a page in one call in its own markdown — headings, lists, tables, code, links. The integration adds nothing and cuts nothing: a long page stays long, and a database entry arrives flat — each property as text according to its type.
Answers where the question was asked — and with a page when it is a report
A mention of the bot in words or a slash command in a comment starts a question, research or a draft task; the answer arrives in the same discussion thread. A research report is a child page under the one where the question was asked, with the text and a PDF; a link to it arrives in the thread.
The roots are the scope
The connection lists the root pages and databases; the bot works in them and in everything nested, and reads and writes only there. An empty list means “everything open to the integration in Notion” — that boundary was already drawn by Notion itself when you connected the integration to sections.
Events by webhook, polling as a safety net
Notion has no comment feed, so its call is parsed: the comment.created event names the comment, and the answer arrives within seconds. Polling goes round the pages in scope as a safety net — every 5 seconds by default; the interval can be changed in the connection settings. The integration respects Notion’s limits: a 429 response is waited out the way Notion itself asks.
The connector receives the signing token itself
Notion signs calls with its verification token, which it sends in the first call. The connector remembers it and shows it on the connection page — all you have to do is paste it into the verification form in Notion. When a subscription is recreated, the connector does not silently accept the new token: it shows it and waits for your decision.
How to use it
Everything happens on the machine where the connector runs. At no step do you need to open access to your network from outside.
Step 1
Installation takes one click
Open the “Marketplace” section on the connector’s local page. Before installing you can see what the integration will get: the address it will be able to reach, which credentials it will ask for and how many tools the model will see. The connector downloads a signed bundle from our registry and checks the signature before writing anything to disk.
Connector← scroll the frame →
The access limits are written on the catalogue card. Step 2
Create an internal integration in Notion
In the workspace settings, create an internal integration with permission to read and insert content and comments. Copy its secret — that is the token for the connector. Then connect the integration to the root pages of the sections through the “…” → “Connections” menu: everything nested opens along with them.
Step 3
Setup: roots, an alias and an interval
The API address is filled in. Name the roots — links or identifiers of pages and databases, separated by commas (empty means everything open to the integration), a short name for the bot, for example `buff`, and, if you like, the polling interval. The secret is stored on your machine; the integration does not see it.
Connector← scroll the frame →
Each integration has its own form fields. Step 4
Address it in words, not with @
An integration cannot be @-mentioned in Notion — it is not a person. Write its name as text: `@buff how do we usually…` or `/research …`. Case does not matter.
Step 5
The same from the command line
Installing without a GUI is an equal option, not a fallback: `connector install notion`, then `connector instance set --plugin notion --version 1.0.0 --set roots=https://www.notion.so/… --poll 5`.
Step 6
Events arrive on their own
Polling always works and needs no ports. For answers to arrive within seconds, turn on event receiving in the connector, enter the issued link in the Notion integration’s webhooks and confirm the subscription with the token the connector shows on the connection page; subscribe to the comment.created event.
Connector← scroll the frame →
Each connection has its own set of tools and its own allowed address.
Access limits
The connector shows the same on your machine before installation. The list comes from the signed catalogue, not written here by hand.
Goes out to
only the addresses from the fields base_url
Credentials
api — the values stay in the connector, the integration does not see them
Webhooks
deliver — you open the port, if you choose to
| Tool | What it does | Access |
|---|---|---|
| search_pages | Find pages and databases by words in the title — when the answer may already be written down in Notion | read only |
| get_page | Read a whole page — as text with headings, lists, tables and code — together with its discussion | read only |
| get_page_children | List the nested pages and databases of a section — when the answer comes together from several pages | read only |
| get_database | Structure of a database — its data sources and properties with their types | read only |
| query_database | Read database entries, optionally filtered by a property value | read only |
| get_comments | Page discussions — comment threads, who wrote and when | read only |
| add_comment | Write a comment on a page or reply in a discussion thread | writes |
| create_page | Create a page inside one of the connected pages — from markdown | writes |
The integration runs as a separate process under its own operating system user: it does not see the connector’s key, does not read the files of other connections and cannot reach the network past the connector. More in the security section.
Requirements
- Notion is cloud-based; API version 2026-03-11 (reading and writing pages as markdown, file uploads).
- An internal Notion integration with permission to read and insert content and comments; reading user information is optional, for authors’ names.
- The integration is connected to the root pages or databases of the sections where the bot works.
- Connector 0.8 or later: the per-connection polling interval and the signing token from the source were added in it; an older connector will refuse to install the integration and name both versions.
- Network access from the connector’s machine to api.notion.com — nothing needs to be opened from your network to the outside; the webhook is optional, only for speed.
- A connector run with the right to create a separate OS user for the integration (root or CAP_SETUID).
Questions
- Will you copy our Notion to your side?
- No. The integration reads pages and entries at the model’s request when an answer requires it, and transfers or indexes nothing in advance. What is read enters the context of a specific answer — not a store.
- Why does the bot not answer if I type @ and pick the integration?
- Because Notion does not let you pick an integration in the @ suggestions — it is not a person. Write the name in words: `@buff …` or use a slash command.
- Will the bot be able to change anything on the pages?
- It does not edit existing pages or database entries. It writes comments and creates new pages — only within its scope and only when asked: a research report or a direct request from the model at a writing stage.
- Notion searches only titles — how will the bot find a page by its text?
- On its own: if the titles do not match, the integration reads the pages in scope and looks for the words in the text, comparing them by stem — word endings do not get in the way. A page is read once until its next edit, so a second question about the same scope costs nothing. In a large scope the first search takes noticeable time.
- How do I limit what it sees?
- In two ways at once: connect the integration in Notion only to the sections needed, and list the roots in the connection settings. An empty list of roots means “everything open to the integration”, so the first boundary is mandatory.
- Why poll every 5 seconds if there is a webhook?
- The webhook is the main path; polling is a safety net in case a call does not arrive. An idle pass costs one request to Notion, which fits within its limit with room to spare; the interval can be increased in the connection settings.
Next
Connect Notion
Install the connector in your network, open its local page and install the integration from the catalogue. Nothing needs to be rebuilt.
Companies and sole traders can pay by bank transfer and receive closing documents