Skip to main content

​
Overview

The n8n API provides programmatic access to SO1’s workflow automation infrastructure. Create, modify, and execute n8n workflows, manage webhook triggers, and monitor workflow performance.
Base URL: https://api.so1.io/v1/n8nThis API wraps n8n’s native API with SO1-specific enhancements for authentication, rate limiting, and integration with agents and orchestration.

​
API Architecture

The n8n API is organized into three main categories:

Workflows

Create, update, and manage workflow definitions

Executions

Trigger and monitor workflow executions

Webhooks

Configure webhook triggers and integrations

​
What is n8n?

n8n is SO1’s workflow automation platform, providing:
  • Visual Workflow Builder: Drag-and-drop interface for creating automations
  • 400+ Integrations: Pre-built nodes for popular services
  • Custom Code: JavaScript/TypeScript execution for complex logic
  • Error Handling: Built-in retry logic and error workflows
  • Scheduling: Cron-based and interval-based triggers
  • Data Transformation: Powerful data manipulation capabilities
Integration: n8n workflows can trigger SO1 agents, creating powerful hybrid automation + AI workflows.

​
Quick Start

​
Create a Workflow

curl -X POST https://api.so1.io/v1/n8n/workflows \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Onboarding Automation",
    "nodes": [
      {
        "name": "Webhook Trigger",
        "type": "n8n-nodes-base.webhook",
        "position": [250, 300],
        "parameters": {
          "path": "user-signup",
          "method": "POST"
        }
      },
      {
        "name": "Create User Record",
        "type": "n8n-nodes-base.postgres",
        "position": [450, 300],
        "parameters": {
          "operation": "insert",
          "table": "users",
          "columns": "email,name,created_at"
        }
      },
      {
        "name": "Send Welcome Email",
        "type": "n8n-nodes-base.sendGrid",
        "position": [650, 300],
        "parameters": {
          "template": "welcome-email"
        }
      }
    ],
    "connections": {
      "Webhook Trigger": {
        "main": [[{ "node": "Create User Record", "type": "main", "index": 0 }]]
      },
      "Create User Record": {
        "main": [[{ "node": "Send Welcome Email", "type": "main", "index": 0 }]]
      }
    },
    "active": true
  }'

​
Execute a Workflow

curl -X POST https://api.so1.io/v1/n8n/workflows/user-onboarding/execute \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "email": "user@example.com",
      "name": "John Doe"
    }
  }'

​
Monitor Execution

curl -X GET https://api.so1.io/v1/n8n/executions/exec-abc123 \
  -H "Authorization: Bearer so1_key_abc123xyz"

​
Authentication

All n8n API requests require a valid API key: 
Authorization: Bearer so1_key_abc123xyz789
See Authentication for API key management.

​
Common Use Cases

​
Trigger Agent from Workflow

Integrate SO1 agents into n8n workflows: 
{
  "name": "Deploy with Validation",
  "nodes": [
    {
      "name": "Trigger",
      "type": "n8n-nodes-base.webhook"
    },
    {
      "name": "Run Pipeline Auditor",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.so1.io/v1/control-plane/agents/execute",
        "method": "POST",
        "authentication": "genericCredentialType",
        "body": {
          "agentId": "pipeline-auditor",
          "taskType": "audit-deployment",
          "context": {
            "service": "{{$json.service}}",
            "environment": "{{$json.environment}}"
          }
        }
      }
    },
    {
      "name": "Deploy if Audit Passes",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "boolean": [
            {
              "value1": "={{$json.result.auditPassed}}",
              "value2": true
            }
          ]
        }
      }
    },
    {
      "name": "Railway Deployment",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.railway.app/deploy"
      }
    }
  ]
}

​
Scheduled Workflow with Error Handling

{
  "name": "Daily Database Backup",
  "nodes": [
    {
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.cron",
      "parameters": {
        "triggerTimes": {
          "item": [{ "mode": "everyDay", "hour": 2, "minute": 0 }]
        }
      }
    },
    {
      "name": "Backup Database",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "executeQuery",
        "query": "COPY (SELECT * FROM users) TO STDOUT WITH CSV HEADER"
      },
      "continueOnFail": true
    },
    {
      "name": "Upload to S3",
      "type": "n8n-nodes-base.aws",
      "parameters": {
        "service": "s3",
        "operation": "upload"
      }
    },
    {
      "name": "Send Error Alert",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#alerts",
        "text": "Database backup failed: {{$json.error}}"
      },
      "executeOnce": true
    }
  ],
  "settings": {
    "errorWorkflow": "error-notification-workflow"
  }
}

​
Multi-Step Approval Workflow

{
  "name": "Deployment Approval Flow",
  "nodes": [
    {
      "name": "Deployment Request",
      "type": "n8n-nodes-base.webhook"
    },
    {
      "name": "Send Approval Request",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#deployments",
        "text": "Approve deployment of {{$json.service}} to production?",
        "attachments": [
          {
            "actions": [
              { "name": "approve", "text": "Approve", "type": "button", "value": "approve" },
              { "name": "reject", "text": "Reject", "type": "button", "value": "reject" }
            ]
          }
        ]
      }
    },
    {
      "name": "Wait for Approval",
      "type": "n8n-nodes-base.wait",
      "parameters": {
        "resume": "webhook",
        "options": {
          "webhook": {
            "path": "approval-response"
          }
        }
      }
    },
    {
      "name": "Check Approval",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "string": [
            {
              "value1": "={{$json.action}}",
              "value2": "approve"
            }
          ]
        }
      }
    },
    {
      "name": "Deploy",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.so1.io/v1/control-plane/agents/execute",
        "body": {
          "agentId": "railway-deployer",
          "taskType": "deploy-service"
        }
      }
    }
  ]
}

​
Response Format

All n8n API responses follow SO1’s standard format:

​
Success Response

{
  "success": true,
  "data": {
    "workflowId": "user-onboarding",
    "version": 1,
    "active": true
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2024-03-10T15:30:00.123Z"
  }
}

​
Error Response

{
  "success": false,
  "error": {
    "code": "WORKFLOW_INVALID",
    "message": "Workflow validation failed: Missing required node parameters",
    "details": {
      "node": "Create User Record",
      "missingParameters": ["table", "columns"]
    }
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2024-03-10T15:30:00.123Z"
  }
}

​
Rate Limits

n8n API endpoints have tier-based rate limits:
TierWorkflow Executions/MinWebhook Triggers/Min
Free1020
Starter60100
Professional300500
Enterprise1,0002,000
See Rate Limits for detailed policies.

​
Best Practices

Create dedicated error handling workflows:
{
  "name": "Error Notification Workflow",
  "nodes": [
    {
      "name": "Error Trigger",
      "type": "n8n-nodes-base.errorTrigger"
    },
    {
      "name": "Format Error",
      "type": "n8n-nodes-base.function",
      "parameters": {
        "functionCode": "return items.map(item => ({\n  workflow: item.json.workflow.name,\n  error: item.json.error.message,\n  timestamp: new Date().toISOString()\n}));"
      }
    },
    {
      "name": "Send to Slack",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#errors",
        "text": "Workflow error: {{$json.workflow}}\\n{{$json.error}}"
      }
    }
  ]
}
Use workflow execution IDs to prevent duplicate processing:
// In a Function node
const executionId = $executionId;
const cache = await $('Redis').getItem(executionId);

if (cache) {
  return []; // Skip processing if already executed
}

// Process workflow logic...

await $('Redis').setItem(executionId, 'processed', { ttl: 86400 });
Break long workflows into smaller sub-workflows:
  • Use webhook waits for human approvals
  • Split into multiple workflows triggered by webhooks
  • Implement checkpoint/resume patterns
  • Use n8n’s built-in retry and timeout settings
  • Store credentials in n8n’s credential system
  • Never hardcode API keys in workflows
  • Use environment variables for configuration
  • Implement webhook signature verification

​
API Endpoints

Workflows API

Create and manage workflow definitions

Executions API

Trigger and monitor workflow runs

Webhooks API

Configure webhook triggers

Workflow Architect Agent

AI agent for designing n8n workflows

Automation Runbook

Operational guide for n8n workflows

Control Plane Workflows API

Higher-level workflow orchestration

Webhook Security

Webhook signature verification