Connect Hermes to Notion
Give your Hermes agent access to Notion in Melso — 53 tools it can call while it works through a task.
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 Hermes 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.