Skip to main content
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.

The tools

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

1

Create it

As a Workspace Owner, go to 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

Use this if other people connect their own workspaces, or each person should choose the pages the agent sees.
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:
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.

Building the Agent

fragment
A typical request takes three calls:
fragment
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. 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.
fragment

Configuration Reference

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