Orchestration API - SO1 Documentation

Overview

The Orchestration API enables complex multi-agent workflows with FORGE stage coordination, gate validation, and dependency management. Use this API to orchestrate sophisticated automation sequences across agents and workflows.

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

Create Orchestration

Start a new multi-agent orchestration with FORGE coordination.

Endpoint

POST /v1/control-plane/orchestration/create

Request Body

name

string

required

Human-readable orchestration name

description

string

Orchestration purpose and goals

stages

array

required

FORGE stages to execute in sequence

Show Stage object properties

stage

string

required

FORGE stage: RESEARCH, DESIGN, IMPLEMENT, VERIFY, DEPLOY, MONITOR

tasks

array

required

Agent tasks to execute in this stage

gateValidation

object

Entry/exit gate requirements

parallel

boolean

default:"false"

Execute tasks in parallel vs sequential

webhook

object

Completion webhook configuration

Example Request

curl -X POST https://api.so1.io/v1/control-plane/orchestration/create \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Full Stack Feature Implementation",
    "description": "Implement user authentication feature across backend, frontend, and docs",
    "stages": [
      {
        "stage": "RESEARCH",
        "tasks": [
          {
            "agentId": "prompt-refiner",
            "taskType": "analyze-requirements",
            "context": { "feature": "user-authentication" }
          }
        ],
        "gateValidation": {
          "exit": {
            "required": ["requirements-documented", "architecture-reviewed"]
          }
        }
      },
      {
        "stage": "DESIGN",
        "tasks": [
          {
            "agentId": "hono-backend",
            "taskType": "design-api",
            "context": { "endpoints": ["/auth/login", "/auth/register"] }
          },
          {
            "agentId": "nextjs-frontend",
            "taskType": "design-components",
            "context": { "pages": ["login", "register"] }
          }
        ],
        "parallel": true,
        "gateValidation": {
          "exit": {
            "required": ["api-schema-validated", "ui-mockups-approved"]
          }
        }
      },
      {
        "stage": "IMPLEMENT",
        "tasks": [
          {
            "agentId": "hono-backend",
            "taskType": "implement-endpoints",
            "context": { "api": "authentication" },
            "dependencies": ["stage:DESIGN"]
          },
          {
            "agentId": "nextjs-frontend",
            "taskType": "implement-components",
            "context": { "feature": "auth-ui" },
            "dependencies": ["stage:DESIGN"]
          },
          {
            "agentId": "typescript-shared",
            "taskType": "create-types",
            "context": { "module": "auth" },
            "dependencies": []
          }
        ],
        "parallel": false
      },
      {
        "stage": "VERIFY",
        "tasks": [
          {
            "agentId": "pipeline-auditor",
            "taskType": "run-tests",
            "context": { "scope": "authentication" }
          }
        ]
      },
      {
        "stage": "DEPLOY",
        "tasks": [
          {
            "agentId": "railway-deployer",
            "taskType": "deploy-services",
            "context": { "services": ["api", "frontend"], "environment": "staging" }
          }
        ]
      },
      {
        "stage": "MONITOR",
        "tasks": [
          {
            "agentId": "mintlify-author",
            "taskType": "create-documentation",
            "context": { "feature": "authentication" }
          }
        ]
      }
    ],
    "webhook": {
      "url": "https://your-app.com/webhooks/orchestration",
      "events": ["orchestration.stage_completed", "orchestration.completed", "orchestration.failed"]
    }
  }'

Response

{
  "success": true,
  "data": {
    "orchestrationId": "orch-abc123xyz789",
    "name": "Full Stack Feature Implementation",
    "status": "running",
    "currentStage": "RESEARCH",
    "stages": [
      {
        "stage": "RESEARCH",
        "status": "running",
        "tasksTotal": 1,
        "tasksCompleted": 0
      },
      {
        "stage": "DESIGN",
        "status": "pending",
        "tasksTotal": 2
      }
      // ... more stages
    ],
    "createdAt": "2024-03-10T15:30:00Z",
    "estimatedCompletionAt": "2024-03-10T15:45:00Z"
  }
}

Get Orchestration Status

Retrieve detailed status of a running or completed orchestration.

Endpoint

GET /v1/control-plane/orchestration/status/{orchestrationId}

Path Parameters

orchestrationId

string

required

Orchestration identifier

Query Parameters

includeTaskDetails

boolean

default:"false"

Include individual task execution details

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/orchestration/status/orch-abc123?includeTaskDetails=true" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

Example Response (Running)

{
  "success": true,
  "data": {
    "orchestrationId": "orch-abc123xyz789",
    "name": "Full Stack Feature Implementation",
    "status": "running",
    "currentStage": "IMPLEMENT",
    "progress": {
      "stagesCompleted": 2,
      "stagesTotal": 6,
      "overallPercentage": 45
    },
    "stages": [
      {
        "stage": "RESEARCH",
        "status": "completed",
        "startedAt": "2024-03-10T15:30:00Z",
        "completedAt": "2024-03-10T15:31:30Z",
        "duration": 90,
        "tasks": [
          {
            "taskId": "task-xyz123",
            "agentId": "prompt-refiner",
            "status": "completed",
            "result": { "requirementsDocumented": true }
          }
        ],
        "gateValidation": {
          "exitGatePassed": true,
          "outputs": ["requirements-documented", "architecture-reviewed"]
        }
      },
      {
        "stage": "DESIGN",
        "status": "completed",
        "startedAt": "2024-03-10T15:31:30Z",
        "completedAt": "2024-03-10T15:33:45Z",
        "duration": 135,
        "tasks": [
          {
            "taskId": "task-abc456",
            "agentId": "hono-backend",
            "status": "completed"
          },
          {
            "taskId": "task-def789",
            "agentId": "nextjs-frontend",
            "status": "completed"
          }
        ]
      },
      {
        "stage": "IMPLEMENT",
        "status": "running",
        "startedAt": "2024-03-10T15:33:45Z",
        "tasks": [
          {
            "taskId": "task-ghi012",
            "agentId": "hono-backend",
            "status": "running",
            "progress": 67
          },
          {
            "taskId": "task-jkl345",
            "agentId": "nextjs-frontend",
            "status": "pending"
          }
        ]
      }
      // ... remaining stages
    ],
    "createdAt": "2024-03-10T15:30:00Z",
    "estimatedCompletionAt": "2024-03-10T15:45:00Z"
  }
}

Example Response (Completed)

{
  "success": true,
  "data": {
    "orchestrationId": "orch-abc123xyz789",
    "name": "Full Stack Feature Implementation",
    "status": "completed",
    "result": {
      "success": true,
      "stagesCompleted": 6,
      "tasksCompleted": 11,
      "outputs": {
        "filesCreated": 23,
        "testsAdded": 15,
        "deploymentUrl": "https://app-staging.railway.app"
      }
    },
    "createdAt": "2024-03-10T15:30:00Z",
    "completedAt": "2024-03-10T15:44:12Z",
    "duration": 852
  }
}

Validate FORGE Gate

Manually validate entry or exit gates for a FORGE stage.

Endpoint

POST /v1/control-plane/orchestration/validate-gate

Request Body

stage

string

required

FORGE stage to validate

gateType

string

required

entry or exit gate

outputs

object

required

Stage outputs to validate against gate criteria

Example Request

curl -X POST https://api.so1.io/v1/control-plane/orchestration/validate-gate \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "IMPLEMENT",
    "gateType": "entry",
    "outputs": {
      "designApproved": true,
      "apiSchemaValidated": true,
      "mockupsReviewed": true
    }
  }'

Response

Success

{
  "success": true,
  "data": {
    "stage": "IMPLEMENT",
    "gateType": "entry",
    "passed": true,
    "criteria": [
      { "name": "designApproved", "required": true, "met": true },
      { "name": "apiSchemaValidated", "required": true, "met": true },
      { "name": "mockupsReviewed", "required": false, "met": true }
    ],
    "validatedAt": "2024-03-10T15:35:00Z"
  }
}

Failure

{
  "success": true,
  "data": {
    "stage": "DEPLOY",
    "gateType": "entry",
    "passed": false,
    "criteria": [
      { "name": "testsPass", "required": true, "met": false },
      { "name": "codeReviewed", "required": true, "met": true },
      { "name": "securityScan", "required": true, "met": false }
    ],
    "missingCriteria": ["testsPass", "securityScan"],
    "validatedAt": "2024-03-10T15:35:00Z"
  }
}

Pause/Resume Orchestration

Pause a running orchestration or resume a paused one.

Endpoints

POST /v1/control-plane/orchestration/{orchestrationId}/pause
POST /v1/control-plane/orchestration/{orchestrationId}/resume

Example Request

# Pause
curl -X POST https://api.so1.io/v1/control-plane/orchestration/orch-abc123/pause \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Manual gate review required"}'

# Resume
curl -X POST https://api.so1.io/v1/control-plane/orchestration/orch-abc123/resume \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "orchestrationId": "orch-abc123",
    "status": "paused",
    "pausedAt": "2024-03-10T15:40:00Z",
    "currentStage": "VERIFY"
  }
}

Cancel Orchestration

Cancel a running or paused orchestration.

Endpoint

POST /v1/control-plane/orchestration/{orchestrationId}/cancel

Request Body

reason

string

Cancellation reason

cancelRunningTasks

boolean

default:"true"

Cancel currently executing agent tasks

Example Request

curl -X POST https://api.so1.io/v1/control-plane/orchestration/orch-abc123/cancel \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Requirements changed",
    "cancelRunningTasks": true
  }'

Response

{
  "success": true,
  "data": {
    "orchestrationId": "orch-abc123",
    "status": "cancelled",
    "cancelledAt": "2024-03-10T15:42:00Z",
    "tasksCancelled": 3
  }
}

List Orchestrations

Retrieve all orchestrations with filtering and pagination.

Endpoint

GET /v1/control-plane/orchestration/list

Query Parameters

status

string

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

stage

string

Filter by current FORGE stage

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/orchestration/list?status=running&limit=10" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "orchestrations": [
      {
        "orchestrationId": "orch-abc123",
        "name": "Full Stack Feature Implementation",
        "status": "running",
        "currentStage": "IMPLEMENT",
        "progress": 45,
        "createdAt": "2024-03-10T15:30:00Z"
      }
      // ... more orchestrations
    ],
    "pagination": {
      "total": 47,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}

Common Patterns

Sequential Multi-Agent Workflow

const orchestration = await fetch(
  'https://api.so1.io/v1/control-plane/orchestration/create',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Documentation Pipeline',
      stages: [
        {
          stage: 'RESEARCH',
          tasks: [{
            agentId: 'prompt-refiner',
            taskType: 'extract-specifications',
            context: { source: '/agents/automation/' }
          }]
        },
        {
          stage: 'IMPLEMENT',
          tasks: [{
            agentId: 'mintlify-author',
            taskType: 'create-agent-docs',
            context: { agentCount: 3 },
            dependencies: ['stage:RESEARCH']
          }],
          parallel: false
        },
        {
          stage: 'VERIFY',
          tasks: [{
            agentId: 'api-documenter',
            taskType: 'validate-links',
            dependencies: ['stage:IMPLEMENT']
          }]
        }
      ]
    })
  }
);

Parallel Task Execution with Dependencies

const orchestration = {
  name: 'Full Stack Deployment',
  stages: [
    {
      stage: 'IMPLEMENT',
      parallel: true, // Run backend and frontend in parallel
      tasks: [
        {
          agentId: 'hono-backend',
          taskType: 'implement-api',
          context: { feature: 'payments' }
        },
        {
          agentId: 'nextjs-frontend',
          taskType: 'implement-ui',
          context: { feature: 'payments' }
        }
      ]
    },
    {
      stage: 'DEPLOY',
      parallel: false,
      tasks: [
        {
          agentId: 'railway-deployer',
          taskType: 'deploy-backend',
          dependencies: ['stage:IMPLEMENT'] // Wait for IMPLEMENT completion
        },
        {
          agentId: 'railway-deployer',
          taskType: 'deploy-frontend',
          dependencies: ['stage:IMPLEMENT']
        }
      ]
    }
  ]
};

Gate Validation Before Stage Transition

async function validateAndProceed(orchestrationId: string, stage: string) {
  // Validate exit gate
  const validation = await fetch(
    'https://api.so1.io/v1/control-plane/orchestration/validate-gate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        stage,
        gateType: 'exit',
        outputs: {
          testsPass: true,
          codeReviewed: true,
          securityScan: true
        }
      })
    }
  );
  
  const { data } = await validation.json();
  
  if (!data.passed) {
    console.error('Gate validation failed:', data.missingCriteria);
    // Pause orchestration for manual review
    await fetch(
      `https://api.so1.io/v1/control-plane/orchestration/${orchestrationId}/pause`,
      {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );
    return false;
  }
  
  return true;
}

Error Codes

Code	Description	Resolution
`ORCHESTRATION_NOT_FOUND`	Orchestration ID does not exist	Verify orchestration ID
`STAGE_DEPENDENCY_FAILED`	Previous stage did not complete successfully	Check stage error details
`GATE_VALIDATION_FAILED`	FORGE gate criteria not met	Provide required outputs
`TASK_DEPENDENCY_CYCLE`	Circular dependency detected	Review task dependencies
`MAX_CONCURRENT_ORCHESTRATIONS`	Too many active orchestrations	Wait for completions or upgrade tier

FORGE Stages

6-stage execution model and gate requirements

Agents API

Execute individual agents

Workflows API

n8n workflow coordination

Factory Orchestrator

Automated orchestration agent

API Reference

Control Plane API

Veritas API

n8n API

​Overview

​Create Orchestration

​Endpoint

​Request Body

​Example Request

​Response

​Get Orchestration Status

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Response

​Validate FORGE Gate

​Endpoint

​Request Body

​Example Request

​Response

​Pause/Resume Orchestration

​Endpoints

​Example Request

​Response

​Cancel Orchestration

​Endpoint

​Request Body

​Example Request

​Response

​List Orchestrations

​Endpoint

​Query Parameters

​Example Request

​Response

​Common Patterns

​Sequential Multi-Agent Workflow

​Parallel Task Execution with Dependencies

​Gate Validation Before Stage Transition

​Error Codes

​Related Resources

FORGE Stages

Agents API

Workflows API

Factory Orchestrator

Overview

Create Orchestration

Endpoint

Request Body

Example Request

Response

Get Orchestration Status

Endpoint

Path Parameters

Query Parameters

Example Request

Response

Validate FORGE Gate

Endpoint

Request Body

Example Request

Response

Pause/Resume Orchestration

Endpoints

Example Request

Response

Cancel Orchestration

Endpoint

Request Body

Example Request

Response

List Orchestrations

Endpoint

Query Parameters

Example Request

Response

Common Patterns

Sequential Multi-Agent Workflow

Parallel Task Execution with Dependencies

Gate Validation Before Stage Transition

Error Codes

Related Resources