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

# Notion Assistant

> Let an agent search, read and write Notion pages and databases, connected through OAuth or an API key

This guide shows how to:

* Connect Timbal to Notion with **OAuth** (a public integration users sign in to) or an **API key** (an internal integration)
* Give an agent ten Notion tools: search, read pages as Markdown, query databases, create and update pages, append content, comment
* Ship the tools and their instructions together as a Skill

The complete example lives in [`examples/notion`](https://github.com/timbal-ai/timbal/tree/main/examples/notion).

## The tools

| Tool | What it does |
| - | - |
| `NotionWhoAmI` (`notion_whoami`) | The integration, its workspace and owner, and the auth method in use. |
| `NotionSearch` (`notion_search`) | Pages and databases shared with the integration, by title. |
| `NotionGetPage` (`notion_get_page`) | A page's properties and its body as Markdown. |
| `NotionGetDataSource` (`notion_get_data_source`) | A database's columns, types and select/status options. |
| `NotionQueryDataSource` (`notion_query_data_source`) | Database rows, with Notion filters and sorts. |
| `NotionCreatePage` (`notion_create_page`) | A sub-page or a database row, with Markdown content. |
| `NotionUpdatePage` (`notion_update_page`) | Rename, set properties, move to or restore from the trash. |
| `NotionAppendContent` (`notion_append_content`) | Markdown appended to a page. |
| `NotionAddComment` / `NotionListComments` | Comment on a page, read its open comments. |

Every ID argument also accepts a notion.so URL, and a database ID or a data source ID both work where a database is expected.

## Setup Requirements

> [accordion] Installing Packages
>
> ```bash theme={"dark"}
> pip install timbal python-dotenv
> ```

> [accordion] Creating the integration in Notion
>
> **1. Create it**
>
> As a **Workspace Owner**, go to [notion.so/profile/integrations](https://www.notion.so/profile/integrations), click **New integration**, pick the workspace and a name.
>
> **2. Choose the type**
>
> * **Internal** for an API key.
> * **Public** for OAuth. Notion asks for company details and the **Redirect URIs**: add `http://localhost:8766/callback` for the example's sign-in script.
>
> **3. Set the capabilities**
>
> Read, update and insert content; read and insert comments. *User information without email* is enough for `notion_whoami`.
>
> **4. Copy the credentials**
>
> Internal: the **Internal Integration Secret**. Public: the **OAuth client ID** and **client secret**.

## Choose an Authentication Method

> [tab] OAuth (public integration)
>
> **Use this if** other people connect their own workspaces, or each person should choose the pages the agent sees.
>
> ```bash theme={"dark"}
> NOTION_CLIENT_ID=your_oauth_client_id
> NOTION_CLIENT_SECRET=your_oauth_client_secret
> ```
>
> Sign in once with the example's script. It opens Notion's consent page, where you pick the pages to share, and saves the tokens to `.notion_token.json`, readable by you only:
>
> ```bash theme={"dark"}
> python setup_credentials.py
> ```
>
> ```bash theme={"dark"}
> NOTION_AUTH_METHOD=oauth
> NOTION_TOKEN_FILE=.notion_token.json
> ```
>
> Notion issues a new refresh token on every refresh. The tools write the newest one back to the token file and refresh under a lock that also holds across processes, so a restart or a second process never reuses a spent token. A token Notion rejects is refreshed once and the call retried. On the Timbal platform, a Notion OAuth integration supplies the access token instead (pass `integration=`). The platform refreshes it, so the tools never exchange an integration's refresh token; a token Notion rejects is fetched from the integration again.

> [tab] API key (internal integration)
>
> **Use this if** the agent works in your own workspace and you want one secret, no sign-in.
>
> ```bash theme={"dark"}
> NOTION_API_KEY=ntn_...
> ```
>
> Then share each page or database the agent should see: open it in Notion, **`•••`** > **Connections**, and add the integration. Sub-pages are shared with their parent.

## Building the Agent

```python fragment theme={"dark"}
from timbal import Agent
from timbal.tools import (
    NotionAppendContent,
    NotionCreatePage,
    NotionGetDataSource,
    NotionGetPage,
    NotionQueryDataSource,
    NotionSearch,
)

agent = Agent(
    name="notion_assistant",
    model="anthropic/claude-sonnet-4-6",
    max_tokens=4096,
    max_iter=15,
    system_prompt=(
        "You help the user with their Notion workspace. Search before you act, read a database's "
        "schema before querying or writing it, and never invent a page, property or option."
    ),
    tools=[
        NotionSearch(),
        NotionGetPage(),
        NotionGetDataSource(),
        NotionQueryDataSource(),
        NotionCreatePage(),
        NotionAppendContent(),
    ],
)

result = await agent(prompt="Which tasks in the Tasks database are due this week?").collect()
print(result.output.collect_text())
```

A typical request takes three calls:

```python fragment theme={"dark"}
notion_search(query="Tasks", object_type="data_source")
notion_get_data_source(database_id="https://www.notion.so/acme/...")
notion_query_data_source(
    database_id="...",
    filter={"and": [
        {"property": "Due", "date": {"this_week": {}}},
        {"property": "Status", "status": {"does_not_equal": "Done"}},
    ]},
)
```

Page content is read and written as Markdown: headings, bulleted and numbered lists, to-dos, quotes, code fences, dividers, **bold**, *italic*, `code` and links. Long content is split to Notion's limits (2,000 characters per text segment, 100 blocks per request).

### Shipping the instructions as a Skill

The example packages the tools with their instructions as a [Skill](https://docs.timbal.ai/agents/skills.md). `skills/notion/SKILL.md` tells the agent to search before acting and read the schema before writing. It also shows Notion's filter and property formats and what to do when a page isn't shared. `skills/notion/tools/notion_tools.py` creates the tools.

```python fragment theme={"dark"}
agent = Agent(
    name="notion_assistant",
    model="anthropic/claude-sonnet-4-6",
    max_tokens=4096,
    skills_path="./skills",
)
```

## Configuration Reference

| Field | Env var | Method |
| - | - | - |
| `api_key` | `NOTION_API_KEY` | API key |
| `token` | `NOTION_ACCESS_TOKEN` | OAuth |
| `refresh_token` | `NOTION_REFRESH_TOKEN` | OAuth (with client ID and secret) |
| `token_file` | `NOTION_TOKEN_FILE` | OAuth: where the newest refresh token is kept |
| `client_id`, `client_secret` | `NOTION_CLIENT_ID`, `NOTION_CLIENT_SECRET` | OAuth refresh |
| `auth_method` | `NOTION_AUTH_METHOD` | pins `oauth` or `api_key` |
| `notion_version` | `NOTION_VERSION` | the `Notion-Version` header (default `2026-03-11`) |
| `integration` | | a Timbal platform integration: an OAuth `token` (the platform refreshes it) or an `api_key`. The env vars above, and the token file they name, are not read when it is set |

> [!NOTE]
>
> When `auth_method` is not set, OAuth credentials are tried before the API key. Rate limits (`429`, `529`) are retried after Notion's `Retry-After`.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| `object_not_found` / "not shared with this integration" | Share the page: `•••` > Connections > your integration. With OAuth, sign in again and select it. |
| `401 ... check NOTION_API_KEY` | The secret is wrong or the integration was deleted. |
| `invalid_grant` on the refresh | The refresh token was revoked or already used. Sign in again and keep `NOTION_TOKEN_FILE` set. |
| `invalid_client` | Wrong OAuth client ID or secret. |
| `validation_error` on a filter or property | A property name or option doesn't match the schema: check `notion_get_data_source`. |
| "Database ... has 2 data sources" | Pass the data source ID the message lists. |


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