Connect your AI agent to Notion
Notion centralizes notes, docs, wikis, and tasks in a unified workspace, letting teams build custom workflows for collaboration and knowledge management
Set it up in Melso
- 1In Melso, open Settings → Agent Apps and hit Connect on Notion.
- 2Finish the OAUTH2 / API_KEY sign-in in the window that opens. Melso stores the connection, not your credentials.
- 3Open your agent, go to its Agent Apps tab, and allow Notion.
- 4Give the agent a task. It calls Notion itself when the work needs it.
What Notion gives your agent
The tools, permissions, and events Notion exposes — the same ones your agent can use once the app is authorized.
What you sign in with
Notion connects with OAUTH2 / API_KEY.
- Client id
- Client secret
Permissions
Notion does not break access down into granular permissions.
Tools Notion exposes
Add multiple content blocks (bulk, user-friendly)
Bulk-add content blocks to Notion. Text >2000 chars auto-splits. Parses markdown formatting. ⚠️ PARENT BLOCK TYPES: Content is added AS CHILDREN of parent_block_id. - To add content AFTER a heading, use PAGE ID as parent + heading ID in 'after' param. - Headings CANNOT have children unless is_toggleable=True. Simplified format: {'content': 'text', 'block_property': 'paragraph'} Full format for code: {'type': 'code', 'code': {'rich_text': [...], 'language': 'python'}} Array format also supported (auto-normalized): [{"parent_block_id": "..."}, {block1}, {block2}] => proper request structure
Add single content block to Notion page (Deprecated)
DEPRECATED: Use 'add_multiple_page_content' for better performance. Adds a single content block to a Notion page/block. CRITICAL: Notion API enforces a HARD LIMIT of 2000 characters per text.content field. Content exceeding 2000 chars is AUTOMATICALLY SPLIT into multiple sequential blocks. REQUIRED 'content' field for text blocks: paragraph, heading_1-3, callout, to_do, toggle, quote, list items. Parent blocks MUST be: Page, Toggle, To-do, Bulleted/Numbered List Item, Callout, or Quote. Common errors: - "content.length should be ≤ 2000": Text exceeds API limit (should be auto-handled) - "Content is required for paragraph blocks": Missing 'content' field for text blocks - "object_not_found": Invalid parent_block_id or no integration access For bulk operations, use 'add_multiple_page_content' instead.
Append raw Notion blocks (advanced API)
DEPRECATED: Use NOTION_APPEND_TEXT_BLOCKS, NOTION_APPEND_TASK_BLOCKS, NOTION_APPEND_CODE_BLOCKS, NOTION_APPEND_MEDIA_BLOCKS, NOTION_APPEND_LAYOUT_BLOCKS, or NOTION_APPEND_TABLE_BLOCKS instead. Appends raw Notion API blocks to parent. Text limited to 2000 chars per text.content field. Each block MUST have 'object':'block' and 'type'. Use rich_text arrays for text blocks.
Append code blocks (code, quote, equation)
Append code and technical blocks (code, quote, equation) to a Notion page. Use for: - Code snippets and programming examples (code) - Citations and highlighted quotes (quote) - Mathematical formulas and equations (equation) Supported block types: - code: Code with syntax highlighting (70+ languages including Python, JavaScript, Go, Rust, etc.) - quote: Block quotes for citations - equation: LaTeX/KaTeX mathematical expressions ⚠️ Code content is limited to 2000 characters per text.content field. For longer code, split into multiple code blocks. For other block types, use specialized actions: - append_text_blocks: paragraphs, headings, lists - append_task_blocks: to-do, toggle, callout - append_media_blocks: image, video, audio, files - append_layout_blocks: divider, columns, TOC - append_table_blocks: tables
Append layout blocks (divider, TOC, columns)
Append layout blocks (divider, TOC, breadcrumb, columns) to a Notion page. Supported types: - divider: Horizontal line separator - table_of_contents: Auto-generated from headings - breadcrumb: Page hierarchy navigation - column_list: Multi-column layout (requires 2+ columns, each with 1+ child block) For multi-column layouts, create column_list with column children in one request. Each column must contain at least 1 child block. For other blocks, use: append_text_blocks, append_task_blocks, append_code_blocks, append_media_blocks, or append_table_blocks.
Append media blocks (image, video, audio, files)
Append media blocks (image, video, audio, file, pdf, embed, bookmark) to a Notion page. Use for: - Images and screenshots (image) - YouTube/Vimeo videos or direct video URLs (video) - Audio files and podcasts (audio) - File downloads (file) - PDF documents (pdf) - Embedded content from Twitter, Figma, CodePen, etc. (embed) - Link previews with metadata (bookmark) All media blocks require external URLs. For other block types, use specialized actions: - append_text_blocks: paragraphs, headings, lists - append_task_blocks: to-do, toggle, callout - append_code_blocks: code, quote, equation - append_layout_blocks: divider, columns, TOC - append_table_blocks: tables
Append table blocks
Append table blocks to a Notion page. Use for structured tabular data like spreadsheets, comparison charts, and status trackers. Example: { "table_width": 3, "has_column_header": true, "rows": [ {"cells": [[{"type": "text", "text": {"content": "Col1"}}], [...], [...]]} ] } ⚠️ Cell content limited to 2000 chars per text.content field.
Append task blocks (to-do, toggle, callout)
Append task blocks (to-do, toggle, callout) to a Notion page or block. Supported block types: - to_do: Checkbox items (checkable/uncheckable) - toggle: Collapsible sections - callout: Highlighted boxes with emoji icons All three types support nested children (up to 2 levels of nesting). block_id must be a page or block that supports children (e.g., page, toggle, paragraph, list items, quote, callout, to_do). Blocks like divider, breadcrumb, equation do NOT support children. Limits: 2000 chars per text.content, max 100 blocks per request. For other blocks: append_text_blocks, append_code_blocks, append_media_blocks, append_layout_blocks, append_table_blocks.
Events your agent can react to
Comment Created
Triggers when a new comment is created in Notion. Optional `page_id` filter scopes to comments on a specific page. When omitted, fires for any new comment in the workspace the integration has access to. Requires the 'Read comments' capability on the Notion integration. If a connection was authorized before that capability was enabled, the user must re-authorize the connection for comment events to flow.
Database Created
Triggers when a new Notion database (the container) is created. A database is the post-2025-09-03 container that holds one or more data sources. This trigger fires for the container's creation event (`database.created`), distinct from `NOTION_DATASOURCE_CREATED` which fires when a new data source is added to an existing database. Most customers calling Notion's `POST /v1/databases` (the legacy API) or creating a database via the Notion UI will see this event. Adding a new data source to an existing database fires `data_source.created` instead — use `NOTION_DATASOURCE_CREATED` for that. Notion's payload puts `entity.type: "block"` (the container is a `child_database` block in the content tree) and `entity.id` is the database id.
Data Source Created
Triggers when a new Notion data source is created. Fires workspace-wide. The payload's `data.parent` carries the data source's tree parent (typically the teamspace) for downstream filtering. A single template-based database creation can fire multiple `data_source.created` events at once — one per data source the template instantiates.
Data Source Schema Updated
Triggers when a Notion data source's schema is updated. Fires on column add / remove / rename. Payload includes `data.updated_properties: [{id, name, action}]` so consumers can discriminate the kind of change downstream. Optional `data_source_id` filter scopes to schema changes on a single data source. When omitted, fires for any schema change in the workspace the integration has access to. Note: adding a column also fires `page.properties_updated` once per existing row in the data source. Customers wanting a single structural-change signal should use this trigger.
Page Content Updated
Triggers when the body content of a Notion page is updated. Customer optionally scopes with at most one of: - data_source_id: any row in this data source - page_id: this specific page - parent_page_id: any page whose immediate parent is this page With none set, fires for any page content edit in the workspace the integration has access to. Notion aggregates content edits within a short window (~60s typical).
Page Created
Triggers when a new Notion page is created. Customer optionally scopes with at most one of: - data_source_id: new row in this data source - parent_page_id: new sub-page under this page (immediate parent only) With neither set, fires for any new page in the workspace the integration has access to. Notion sends ~60s aggregation latency on most events.
Use Notion from the agent you already run
Melso runs the agent. You decide which of your authorized apps it may reach.
Hermes
Run Hermes as a Melso agent and let it use the apps you have authorized.
Use Notion from HermesCompare nearby apps
Other Notes connections your agents can use.
Connect to Google Docs
Google Docs is a cloud-based word processor with real-time collaboration, version history, and integration with other Google Workspace apps
Connect to Linear
Linear is a streamlined issue tracking and project planning tool for modern teams, featuring fast workflows, keyboard shortcuts, and GitHub integrations
Connect to Jira
A tool for bug tracking, issue tracking, and agile project management.
Connect to Wrike
Wrike is a project management and collaboration tool offering customizable workflows, Gantt charts, reporting, and resource management to boost team productivity
Connect to Asana
Tool to help teams organize, track, and manage their work.
Connect to DocuSign
DocuSign provides eSignature and digital agreement solutions, enabling businesses to send, sign, track, and manage documents electronically