Integrations / Notion
Notion
First-party Notion API tools for dashboard chat and for AI employees that have the Notion skill. Each user connects with their own token stored as an encrypted credential (not a shared server env var).
What it does
- Search pages and databases in your workspace.
- Read a page’s properties and block children (content).
- Create pages under a parent page or database.
- Append Notion block objects to a page or block.
- Query database rows with optional filters, sorts, and pagination.
Implementation uses the official API (Notion-Version: 2022-06-28 on requests). Tool names in the product align with these actions (for example list/search, get page, create page, append blocks, query database).
Setup steps
Operator prerequisites: Production needs CREDENTIAL_ENCRYPTION_KEY so tokens can be stored; without it, saving credentials fails.
Option A — OAuth (when your operator enables it): they set NOTION_CLIENT_ID, NOTION_CLIENT_SECRET, and PUBLIC_APP_URL on the API, register redirect {PUBLIC_APP_URL}/api/notion/callback on a public Notion integration, then you use Settings → Connect → Notion → Connect, approve in Notion, and return to the dashboard.
Option B — Manual internal integration token: In Notion, create an integration and copy the Internal Integration Secret (secret_…). In CloudyBot, add a credential: service notion, key name NOTION_API_KEY, value your secret. Then share every page or database the bot should access (page menu → … → Connections → your integration).
Status is available via GET /api/notion/status (session auth); it reports whether you are configured and whether OAuth is enabled server-wide.
Common use cases
- Knowledge-backed chat: Search and read Notion pages to answer questions with your own docs.
- CRM or ops databases: Query a shared database with filters and sorts, then summarize or draft follow-ups in chat.
- Capture to Notion: Create pages or append blocks from a conversation when the model uses the create/append tools.
- Specialists: Enable the notion skill on an employee template (for example the native-tools Notion assistant pattern) so scheduled or dedicated workers can use the same tool allowlist.
Database create rows require properties that match that database’s schema; wrong shapes return validation errors from Notion. Block appends must use valid Notion block JSON.
Security note
Tokens are read only through the credential store for your user ID. Do not log token values or full Notion error bodies if they might echo secrets. Treat the integration secret like any production API key.
FAQ
What can CloudyBot do with Notion?
CloudyBot exposes first-party Notion API tools for dashboard chat and for AI employees that have the Notion skill enabled. Today that means: search pages and databases; read a page’s properties and block children; create pages under a parent page or database; append Notion block objects to a page or block; and query database rows with optional filters, sorts, and pagination. Anything outside those tool actions is not supported through this integration.
How do I connect Notion?
If your operator enables OAuth, use Settings → Connect → Notion, approve in Notion, and return to the dashboard; your access token is stored as the NOTION_API_KEY credential (and a workspace label when Notion returns one). Otherwise add a credential for service notion and key NOTION_API_KEY with your Notion internal integration secret (starts with secret_). In both cases you must share each page or database with the integration in Notion (page menu → Connections) or the API returns 404 or object-not-found style errors.
Why do I see “Notion is not configured” or encryption errors when saving?
Tools read your token from stored user credentials. If nothing is saved, status shows configured false and tools report Notion is not configured. Saving credentials in production requires CREDENTIAL_ENCRYPTION_KEY on the API; without a valid key, encryption errors can block saves. Re-check the secret if Notion returns 401.
What should I know about limits and errors?
Rate limits and workspace rules are enforced by Notion. The product may surface 429 as try again later and 401 as re-check the integration or token. Database creates require properties that match the database schema or Notion returns validation errors. Block appends require valid Notion block JSON per Notion’s API. List, search, and query responses may paginate; the model can pass the next cursor on a follow-up call.
Ready to connect? Open the dashboard and go to Settings → Connect for Notion OAuth, or your deployment’s credentials UI for a manual token.
Open dashboard