Workflows API - SO1 Documentation

Overview

The Workflows API provides programmatic access to SO1’s n8n automation infrastructure. Trigger workflows, monitor executions, manage webhooks, and coordinate complex automation sequences.

Base URL: https://api.so1.io/v1/control-plane/workflows

Trigger Workflow

Execute an n8n workflow with custom payload and execution parameters.

Endpoint

POST /v1/control-plane/workflows/trigger

Request Body

workflowId

string

required

Workflow identifier or slug (e.g., deployment-pipeline, wf-abc123)

payload

object

required

Workflow input data (passed to workflow trigger node)

execution

object

Execution configuration

Show properties

mode

string

default:"async"

async (immediate return) or sync (wait for completion)

timeout

number

default:"300"

Maximum execution time in seconds (sync mode only)

priority

string

default:"normal"

Queue priority: low, normal, high, critical

webhook

object

Webhook notification configuration

Show properties

url

string

required

HTTPS endpoint for execution updates

events

array

Events: execution.started, execution.completed, execution.failed, execution.waiting

secret

string

Webhook signing secret

Example Request

curl -X POST https://api.so1.io/v1/control-plane/workflows/trigger \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "deployment-pipeline",
    "payload": {
      "service": "api-gateway",
      "environment": "production",
      "version": "v2.4.1",
      "rollbackOnFailure": true
    },
    "execution": {
      "mode": "async",
      "priority": "high"
    },
    "webhook": {
      "url": "https://your-app.com/webhooks/n8n",
      "events": ["execution.completed", "execution.failed"],
      "secret": "whsec_abc123xyz"
    }
  }'

Response

Example Response (Async)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123xyz789",
    "workflowId": "deployment-pipeline",
    "status": "running",
    "startedAt": "2024-03-10T15:30:00Z",
    "n8nExecutionUrl": "https://n8n.so1.io/execution/exec-abc123xyz789"
  },
  "meta": {
    "requestId": "req-def456",
    "timestamp": "2024-03-10T15:30:00.123Z"
  }
}

Example Response (Sync - Completed)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123xyz789",
    "workflowId": "user-onboarding",
    "status": "completed",
    "result": {
      "success": true,
      "outputs": {
        "userCreated": true,
        "emailSent": true,
        "subscriptionActive": true
      },
      "nodesExecuted": 8,
      "duration": 2.4
    },
    "startedAt": "2024-03-10T15:30:00Z",
    "completedAt": "2024-03-10T15:30:02.4Z"
  }
}

Get Execution Status

Retrieve detailed status and output of a workflow execution.

Endpoint

GET /v1/control-plane/workflows/executions/{executionId}

Path Parameters

executionId

string

required

Execution identifier returned from trigger endpoint

Query Parameters

includeData

boolean

default:"false"

Include full node input/output data

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/workflows/executions/exec-abc123?includeData=true" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

Example Response (Running)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123xyz789",
    "workflowId": "deployment-pipeline",
    "workflowName": "Production Deployment Pipeline",
    "status": "running",
    "progress": {
      "nodesCompleted": 4,
      "nodesTotal": 7,
      "currentNode": "Railway Deploy"
    },
    "startedAt": "2024-03-10T15:30:00Z",
    "estimatedCompletionAt": "2024-03-10T15:33:00Z"
  }
}

Example Response (Completed with Data)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123xyz789",
    "workflowId": "deployment-pipeline",
    "workflowName": "Production Deployment Pipeline",
    "status": "completed",
    "result": {
      "success": true,
      "outputs": {
        "deploymentId": "dep-xyz123",
        "deploymentUrl": "https://api-production.railway.app",
        "healthCheckPassed": true,
        "rollbackRequired": false
      },
      "nodesExecuted": 7,
      "duration": 142.5
    },
    "nodeData": [
      {
        "nodeName": "Validate Version",
        "nodeType": "n8n-nodes-base.function",
        "status": "completed",
        "duration": 0.3,
        "output": { "valid": true, "version": "v2.4.1" }
      },
      {
        "nodeName": "Railway Deploy",
        "nodeType": "n8n-nodes-base.httpRequest",
        "status": "completed",
        "duration": 125.8,
        "output": { "deploymentId": "dep-xyz123", "status": "live" }
      }
      // ... more nodes
    ],
    "startedAt": "2024-03-10T15:30:00Z",
    "completedAt": "2024-03-10T15:32:22.5Z"
  }
}

Example Response (Failed)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123xyz789",
    "workflowId": "deployment-pipeline",
    "status": "failed",
    "error": {
      "code": "NODE_EXECUTION_FAILED",
      "message": "Railway deployment failed: Health check timeout",
      "nodeName": "Railway Deploy",
      "details": {
        "httpStatus": 500,
        "railwayError": "Service failed to respond to health checks after 60s"
      }
    },
    "startedAt": "2024-03-10T15:30:00Z",
    "failedAt": "2024-03-10T15:31:15Z",
    "duration": 75
  }
}

List Workflow Executions

Retrieve paginated list of workflow executions with filtering.

Endpoint

GET /v1/control-plane/workflows/executions

Query Parameters

workflowId

string

Filter by specific workflow

status

string

Filter by status: running, completed, failed, waiting, cancelled

startDate

string

ISO 8601 date - filter executions after this date

endDate

string

ISO 8601 date - filter executions before this date

limit

number

default:"20"

Results per page (1-100)

offset

number

default:"0"

Pagination offset

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/workflows/executions?workflowId=deployment-pipeline&status=completed&limit=10" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "executions": [
      {
        "executionId": "exec-abc123",
        "workflowId": "deployment-pipeline",
        "status": "completed",
        "startedAt": "2024-03-10T15:30:00Z",
        "completedAt": "2024-03-10T15:32:22Z",
        "duration": 142.5
      }
      // ... more executions
    ],
    "pagination": {
      "total": 342,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}

Cancel Execution

Stop a running workflow execution.

Endpoint

POST /v1/control-plane/workflows/executions/{executionId}/cancel

Request Body

reason

string

Cancellation reason (optional, for audit logs)

Example Request

curl -X POST https://api.so1.io/v1/control-plane/workflows/executions/exec-abc123/cancel \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Superseded by newer deployment"}'

Response

{
  "success": true,
  "data": {
    "executionId": "exec-abc123",
    "status": "cancelled",
    "cancelledAt": "2024-03-10T15:35:00Z"
  }
}

List Workflows

Get all available workflows with metadata.

Endpoint

GET /v1/control-plane/workflows

Query Parameters

tag

string

Filter workflows by tag (e.g., deployment, notification, automation)

active

boolean

Filter by active status

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/workflows?tag=deployment&active=true" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "workflows": [
      {
        "workflowId": "deployment-pipeline",
        "name": "Production Deployment Pipeline",
        "description": "Automated deployment to Railway with health checks and rollback",
        "tags": ["deployment", "production", "railway"],
        "active": true,
        "version": 3,
        "nodes": 7,
        "averageDuration": 145.2,
        "executionCount": 1247,
        "successRate": 98.4,
        "lastExecutedAt": "2024-03-10T15:30:00Z",
        "webhookUrl": "https://n8n.so1.io/webhook/deployment-pipeline"
      },
      {
        "workflowId": "user-onboarding",
        "name": "User Onboarding Automation",
        "description": "Create user account, send welcome email, setup workspace",
        "tags": ["automation", "onboarding", "users"],
        "active": true,
        "version": 2,
        "nodes": 8,
        "averageDuration": 3.1,
        "executionCount": 5623,
        "successRate": 99.7,
        "lastExecutedAt": "2024-03-10T15:28:00Z"
      }
    ]
  }
}

Register Webhook

Endpoint

POST /v1/control-plane/workflows/{workflowId}/webhooks

Path Parameters

workflowId

string

required

Workflow to attach webhook

Request Body

path

string

required

Webhook URL path (e.g., /deploy, /github-push)

method

string

required

HTTP method: GET, POST, PUT, PATCH, DELETE

authentication

object

Webhook authentication settings

Show properties

type

string

Auth type: none, apiKey, hmac, oauth

apiKeyHeader

string

Header name for API key auth (e.g., X-API-Key)

hmacSecret

string

Secret for HMAC signature verification

Example Request

curl -X POST https://api.so1.io/v1/control-plane/workflows/deployment-pipeline/webhooks \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/deploy",
    "method": "POST",
    "authentication": {
      "type": "hmac",
      "hmacSecret": "webhook_secret_abc123"
    }
  }'

Response

{
  "success": true,
  "data": {
    "webhookId": "wh-xyz789",
    "workflowId": "deployment-pipeline",
    "url": "https://n8n.so1.io/webhook/deploy",
    "method": "POST",
    "active": true,
    "createdAt": "2024-03-10T15:30:00Z"
  }
}

Workflow Scheduling

Schedule recurring workflow executions.

Endpoint

POST /v1/control-plane/workflows/{workflowId}/schedule

Request Body

cron

string

required

Cron expression (e.g., 0 2 * * * for daily at 2 AM UTC)

timezone

string

default:"UTC"

IANA timezone (e.g., America/New_York)

payload

object

Default payload for scheduled executions

enabled

boolean

default:"true"

Enable schedule immediately

Example Request

curl -X POST https://api.so1.io/v1/control-plane/workflows/backup-database/schedule \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 2 * * *",
    "timezone": "America/New_York",
    "payload": {
      "database": "production",
      "retentionDays": 30
    },
    "enabled": true
  }'

Response

{
  "success": true,
  "data": {
    "scheduleId": "sch-abc123",
    "workflowId": "backup-database",
    "cron": "0 2 * * *",
    "timezone": "America/New_York",
    "nextRunAt": "2024-03-11T02:00:00-04:00",
    "enabled": true
  }
}

Common Patterns

Wait for Workflow Completion

async function waitForWorkflowCompletion(executionId: string): Promise<any> {
  const maxAttempts = 120; // 10 minutes
  
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.so1.io/v1/control-plane/workflows/executions/${executionId}`,
      { headers: { 'Authorization': `Bearer ${process.env.SO1_API_KEY}` } }
    );
    
    const { data } = await response.json();
    
    if (data.status === 'completed') {
      return data.result;
    } else if (data.status === 'failed') {
      throw new Error(data.error.message);
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  
  throw new Error('Workflow timeout');
}

Trigger Workflow with Retry Logic

async function triggerWorkflowWithRetry(
  workflowId: string,
  payload: any,
  maxRetries: number = 3
): Promise<string> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(
        'https://api.so1.io/v1/control-plane/workflows/trigger',
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${process.env.SO1_API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ workflowId, payload })
        }
      );
      
      if (!response.ok) throw new Error('Trigger failed');
      
      const { data } = await response.json();
      return data.executionId;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
    }
  }
  
  throw new Error('Max retries exceeded');
}

Error Codes

Code	Description	Resolution
`WORKFLOW_NOT_FOUND`	Workflow ID does not exist	Check available workflows
`WORKFLOW_INACTIVE`	Workflow is deactivated	Activate workflow in n8n
`EXECUTION_FAILED`	Workflow execution error	Check node error details
`WEBHOOK_INVALID`	Invalid webhook configuration	Verify path and authentication
`SCHEDULE_INVALID`	Invalid cron expression	Use valid cron syntax
`PAYLOAD_TOO_LARGE`	Workflow payload exceeds 5MB	Reduce payload size

Agents API

Execute AI agents within workflows

n8n Integration

n8n workflow development guide

Orchestration API

Multi-workflow coordination

Webhooks

Webhook security and verification

API Reference

Control Plane API

Veritas API

n8n API

​Overview

​Trigger Workflow

​Endpoint

​Request Body

​Example Request

​Response

​Get Execution Status

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Response

​List Workflow Executions

​Endpoint

​Query Parameters

​Example Request

​Response

​Cancel Execution

​Endpoint

​Request Body

​Example Request

​Response

​List Workflows

​Endpoint

​Query Parameters

​Example Request

​Response

​Register Webhook

​Endpoint

​Path Parameters

​Request Body

​Example Request

​Response

​Workflow Scheduling

​Endpoint

​Request Body

​Example Request

​Response

​Common Patterns

​Wait for Workflow Completion

​Trigger Workflow with Retry Logic

​Error Codes

​Related Resources

Agents API

n8n Integration

Orchestration API

Webhooks

Overview

Trigger Workflow

Endpoint

Request Body

Example Request

Response

Get Execution Status

Endpoint

Path Parameters

Query Parameters

Example Request

Response

List Workflow Executions

Endpoint

Query Parameters

Example Request

Response

Cancel Execution

Endpoint

Request Body

Example Request

Response

List Workflows

Endpoint

Query Parameters

Example Request

Response

Register Webhook

Endpoint

Path Parameters

Request Body

Example Request

Response

Workflow Scheduling

Endpoint

Request Body

Example Request

Response

Common Patterns

Wait for Workflow Completion

Trigger Workflow with Retry Logic

Error Codes

Related Resources