- 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
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
Installing Packages
Installing Packages
Creating the integration in Notion
Creating the integration in Notion
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/callbackfor 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
- OAuth (public integration)
- API key (internal integration)
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 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
.notion_token.json, readable by you only: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
fragment
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.