n8n Notion Advanced Nodes

A comprehensive n8n community package that provides complete access to the Notion API v2022-06-28 with support for all block types, rich text formatting, and CRUD operations. Includes both a full-featured workflow node and an AI Agent Tool for intelligent automation.

What's Included

1. Notion Advanced - Full-Featured Workflow Node

Complete Notion integration for traditional n8n workflows with comprehensive CRUD operations and all 25+ block types.

2. Notion AI Tool - AI Agent Integration

Specialized tool designed for n8n's AI Agent Nodes, enabling natural language Notion automation.

📖 For AI Agent usage, see AI-TOOL-USAGE.md

Features

Complete Block Type Support

• Basic Text Blocks: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, to_do, toggle, quote, callout, divider
• Code Blocks: code with syntax highlighting support for 170+ languages
• Media Blocks: image, video, audio, file, pdf with upload and external URL support
• Interactive Blocks: bookmark, embed, link_preview, equation (LaTeX)
• Advanced Layout: table, table_row, column_list, column, synced_block, template, table_of_contents
• Database Integration: child_database, child_page references

Rich Text Formatting

• Annotations: bold, italic, strikethrough, underline, code
• Colors: All 10 text colors and 9 background colors
• Links: Internal page links and external URLs
• Mentions: User, page, database, and date mentions
• Equations: Inline and block LaTeX math expressions

Operations

• Pages: Create, read, update, archive, search with full property support
• Blocks: Create, read, update, delete, get children, append children
• Databases: Get, query, create with complete schema support
• Users: Get, list workspace users

Installation

Via n8n GUI (Recommended)

1. Open n8n Settings → Community Nodes
2. Click "Install a community node"
3. Enter: n8n-nodes-notion-advanced
4. Click Install

Via npm

npm install n8n-nodes-notion-advanced

📖 For detailed installation instructions including Docker setup, development mode, and troubleshooting, see INSTALLATION.md

Quick Start

For AI Agents

1. Add AI Agent Node to your workflow
2. Configure your chat model (OpenAI, Anthropic, etc.)
3. Add "Notion AI Tool" from available tools
4. Configure Notion credentials
5. AI Agent can now create/manage Notion content with natural language!

Example: "Create a project plan page with timeline and milestones"

For Traditional Workflows

1. Add "Notion Advanced" node to your workflow
2. Configure Notion credentials
3. Choose resource (Page/Block/Database/User)
4. Select operation and configure parameters
5. Execute comprehensive Notion operations

Prerequisites

• n8n instance (self-hosted or cloud)
• Notion API integration with appropriate permissions
• Existing notionApi credentials configured in n8n

Usage

Setting up Credentials

This node uses the existing n8n Notion API credentials. Ensure you have:

1. Created a Notion integration at https://developers.notion.com/
2. Added the integration to your Notion workspace
3. Configured the notionApi credential in n8n with your integration token

Basic Examples

Creating a Page

{
  "resource": "page",
  "operation": "create",
  "parent": "page-id-or-url",
  "title": "My New Page",
  "properties": {
    "property": [
      {
        "name": "Status",
        "type": "select",
        "value": "{\"name\": \"In Progress\"}"
      }
    ]
  }
}

Adding Blocks to a Page

{
  "resource": "block",
  "operation": "create",
  "parentId": "page-id",
  "blocks": {
    "block": [
      {
        "type": "paragraph",
        "content": "This is a simple paragraph"
      },
      {
        "type": "heading_1",
        "content": "Main Heading",
        "properties": "{\"color\": \"blue\"}"
      },
      {
        "type": "code",
        "content": "console.log('Hello World');",
        "properties": "{\"language\": \"javascript\"}"
      }
    ]
  }
}

Rich Text with Formatting

{
  "type": "paragraph",
  "richText": "[{\"type\": \"text\", \"text\": {\"content\": \"Bold text\"}, \"annotations\": {\"bold\": true}}, {\"type\": \"text\", \"text\": {\"content\": \" and \"}, \"annotations\": {}}, {\"type\": \"text\", \"text\": {\"content\": \"italic text\", \"link\": {\"url\": \"https://example.com\"}}, \"annotations\": {\"italic\": true, \"color\": \"blue\"}}]"
}

Block Types Reference

Text Blocks

Code Blocks

Supported Languages: JavaScript, Python, Java, C++, HTML, CSS, SQL, JSON, XML, and 160+ more.

Media Blocks

Interactive Blocks

Layout Blocks

Advanced Blocks

Rich Text Formatting

Annotations

{
  "annotations": {
    "bold": true,
    "italic": false,
    "strikethrough": false,
    "underline": true,
    "code": false,
    "color": "blue"
  }
}

Colors

Text Colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red

Background Colors: gray_background, brown_background, orange_background, yellow_background, green_background, blue_background, purple_background, pink_background, red_background

Links

{
  "text": {
    "content": "Link text",
    "link": {
      "url": "https://example.com"
    }
  }
}

Error Handling

The node provides comprehensive error handling:

• Credential Validation: Automatically validates API credentials
• Input Validation: Validates all required fields and block structures
• API Error Mapping: Maps Notion API errors to user-friendly messages
• Graceful Degradation: Continues processing with continueOnFail option

Performance Features

• Pagination Support: Automatically handles paginated responses
• Batch Operations: Efficient bulk block creation and updates
• Credential Caching: Reuses authentication across requests
• Request Optimization: Minimizes API calls with intelligent batching

Troubleshooting

Common Issues

1. Permission Errors: Ensure your Notion integration has access to the target pages/databases
2. Invalid Block Types: Check that all block properties match the expected schema
3. Rate Limiting: The node respects Notion's rate limits automatically
4. Large Content: For pages with many blocks, consider using batch operations

Debug Tips

• Enable n8n's debug mode to see full API requests/responses
• Validate JSON strings in block properties before sending
• Test with simple blocks before adding complex formatting
• Check Notion's API documentation for the latest block schemas

API Reference

This node implements Notion API version 2022-06-28. For the most up-to-date API documentation, visit:
https://developers.notion.com/reference

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section
• Review Notion's API documentation
• Open an issue on GitHub
• Join the n8n community forum