Agents API

Overview

The Agents API allows you to programmatically execute any of the 20 SO1 agents, monitor their execution status, and retrieve results. Agents operate across 7 domains and implement specific capabilities within the FORGE automation framework.

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

Available Agents

SO1 provides 20 production-ready agents across 7 domains:

Domain	Agents	Purpose
Orchestration	factory-orchestrator, forge-gatekeeper	Workflow coordination, gate validation
Automation	workflow-architect, webhook-engineer, schedule-optimizer	n8n workflow management
Engineering	hono-backend, nextjs-frontend, typescript-shared	Code generation
DevOps	railway-deployer, github-actions, pipeline-auditor	Infrastructure management
Documentation	mintlify-author, api-documenter, runbook-writer	Content creation
Prompts	prompt-refiner, chain-architect, fragment-curator	Veritas library management
Incident	incident-commander, triage-responder, postmortem-analyst	Emergency response

See Agent Reference for complete specifications.

Execute Agent

Start an agent execution with specified context and parameters.

Endpoint

POST /v1/control-plane/agents/execute

Request Body

agentId

string

required

Agent identifier (e.g., mintlify-author, hono-backend)

taskType

string

required

Specific task for the agent to perform (agent-specific)

context

object

required

Task-specific context data (varies by agent and task type)

forge

object

FORGE stage and gate validation settings

Show properties

stage

string

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

validateGates

boolean

default:"true"

Enforce entry/exit gate validation

previousStageOutputs

object

Outputs from previous FORGE stages

execution

object

Execution mode and timeout settings

Show properties

mode

string

default:"async"

async (immediate return with taskId) or sync (block until completion)

timeout

number

default:"300"

Maximum execution time in seconds (5-3600)

priority

string

default:"normal"

Queue priority: low, normal, high, critical

webhook

object

Webhook configuration for completion notifications

Show properties

url

string

required

HTTPS endpoint to receive webhook

events

array

Events to trigger webhook: task.started, task.completed, task.failed

secret

string

Webhook signing secret (verify authenticity)

Example Request

curl -X POST https://api.so1.io/v1/control-plane/agents/execute \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "mintlify-author",
    "taskType": "create-agent-reference",
    "context": {
      "agentName": "workflow-architect",
      "sourcePath": "/agents/automation/workflow-architect.md",
      "outputPath": "/docs/agents/automation/workflow-architect.mdx"
    },
    "forge": {
      "stage": "IMPLEMENT",
      "validateGates": true
    },
    "webhook": {
      "url": "https://your-app.com/webhooks/so1",
      "events": ["task.completed", "task.failed"],
      "secret": "whsec_abc123xyz789"
    }
  }'

Response

success

boolean

Indicates if request was accepted

data

object

Show properties

taskId

string

Unique task identifier for status polling

status

string

Current status: queued, running, completed, failed

agentId

string

Agent that will execute the task

createdAt

string

ISO 8601 timestamp of task creation

estimatedDuration

number

Estimated completion time in seconds

Example Response

{
  "success": true,
  "data": {
    "taskId": "task-xyz789abc123",
    "status": "queued",
    "agentId": "mintlify-author",
    "taskType": "create-agent-reference",
    "createdAt": "2024-03-10T15:30:00Z",
    "estimatedDuration": 45
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2024-03-10T15:30:00.123Z"
  }
}

Get Task Status

Retrieve the current status and details of an agent execution.

Endpoint

GET /v1/control-plane/agents/tasks/{taskId}

Path Parameters

taskId

string

required

Task identifier returned from execute endpoint

Example Request

curl -X GET https://api.so1.io/v1/control-plane/agents/tasks/task-xyz789abc123 \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

Example Response (Running)

{
  "success": true,
  "data": {
    "taskId": "task-xyz789abc123",
    "status": "running",
    "agentId": "mintlify-author",
    "taskType": "create-agent-reference",
    "progress": {
      "percentage": 67,
      "currentStep": "Generating code examples",
      "stepsCompleted": 4,
      "stepsTotal": 6
    },
    "createdAt": "2024-03-10T15:30:00Z",
    "startedAt": "2024-03-10T15:30:05Z",
    "estimatedCompletionAt": "2024-03-10T15:30:50Z"
  }
}

Example Response (Completed)

{
  "success": true,
  "data": {
    "taskId": "task-xyz789abc123",
    "status": "completed",
    "agentId": "mintlify-author",
    "taskType": "create-agent-reference",
    "result": {
      "filesCreated": [
        "/docs/agents/automation/workflow-architect.mdx"
      ],
      "filesModified": [],
      "linesWritten": 487,
      "output": {
        "documentationPath": "/docs/agents/automation/workflow-architect.mdx",
        "quality": {
          "completeness": 100,
          "examplesIncluded": true,
          "crossReferencesValid": true
        }
      }
    },
    "createdAt": "2024-03-10T15:30:00Z",
    "startedAt": "2024-03-10T15:30:05Z",
    "completedAt": "2024-03-10T15:30:47Z",
    "duration": 42
  }
}

Example Response (Failed)

{
  "success": true,
  "data": {
    "taskId": "task-xyz789abc123",
    "status": "failed",
    "agentId": "hono-backend",
    "taskType": "implement-endpoint",
    "error": {
      "code": "GATE_VALIDATION_FAILED",
      "message": "Entry gate validation failed: Missing required DESIGN stage outputs",
      "details": {
        "stage": "IMPLEMENT",
        "missingOutputs": ["schemaValidated", "endpointSpec"]
      }
    },
    "createdAt": "2024-03-10T15:30:00Z",
    "startedAt": "2024-03-10T15:30:05Z",
    "failedAt": "2024-03-10T15:30:12Z",
    "duration": 7
  }
}

List Agent Executions

Retrieve a paginated list of agent executions with optional filtering.

Endpoint

GET /v1/control-plane/agents/tasks

Query Parameters

agentId

string

Filter by specific agent

status

string

Filter by status: queued, running, completed, failed

limit

number

default:"20"

Number of results per page (1-100)

offset

number

default:"0"

Pagination offset

sortBy

string

default:"createdAt"

Sort field: createdAt, completedAt, duration

sortOrder

string

default:"desc"

Sort order: asc or desc

Example Request

curl -X GET "https://api.so1.io/v1/control-plane/agents/tasks?agentId=mintlify-author&status=completed&limit=10" \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "tasks": [
      {
        "taskId": "task-xyz789",
        "agentId": "mintlify-author",
        "taskType": "create-agent-reference",
        "status": "completed",
        "createdAt": "2024-03-10T15:30:00Z",
        "completedAt": "2024-03-10T15:30:47Z",
        "duration": 47
      },
      // ... more tasks
    ],
    "pagination": {
      "total": 156,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}

Cancel Task

Cancel a queued or running agent execution.

Endpoint

POST /v1/control-plane/agents/tasks/{taskId}/cancel

Path Parameters

taskId

string

required

Task identifier to cancel

Request Body

reason

string

Reason for cancellation (optional, for audit logs)

Example Request

curl -X POST https://api.so1.io/v1/control-plane/agents/tasks/task-xyz789/cancel \
  -H "Authorization: Bearer so1_key_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Duplicate execution detected"}'

Response

{
  "success": true,
  "data": {
    "taskId": "task-xyz789",
    "status": "cancelled",
    "cancelledAt": "2024-03-10T15:35:00Z"
  }
}

Running Tasks: Tasks in running state may take up to 30 seconds to fully cancel as the agent completes its current operation.

Get Agent Metadata

Retrieve metadata and capabilities for a specific agent.

Endpoint

GET /v1/control-plane/agents/{agentId}

Example Request

curl -X GET https://api.so1.io/v1/control-plane/agents/mintlify-author \
  -H "Authorization: Bearer so1_key_abc123xyz"

Response

{
  "success": true,
  "data": {
    "agentId": "mintlify-author",
    "name": "Mintlify Author",
    "domain": "Documentation",
    "forgeStage": "IMPLEMENT",
    "version": "1.0.0",
    "capabilities": [
      "create-agent-reference",
      "create-runbook",
      "update-navigation"
    ],
    "inputs": {
      "required": ["agentName", "sourcePath"],
      "optional": ["outputPath", "includeExamples"]
    },
    "outputs": {
      "filesCreated": "string[]",
      "documentationPath": "string",
      "quality": "object"
    },
    "averageDuration": 45,
    "successRate": 98.7
  }
}

Common Patterns

Polling for Completion

async function waitForCompletion(taskId: string): Promise<any> {
  const maxAttempts = 120; // 10 minutes with 5s intervals
  
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.so1.io/v1/control-plane/agents/tasks/${taskId}`,
      { 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);
    }
    
    // Still running, wait and retry
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  
  throw new Error('Task timeout after 10 minutes');
}

Batch Agent Execution

async function executeBatch(tasks: AgentTask[]): Promise<string[]> {
  const executions = await Promise.all(
    tasks.map(task =>
      fetch('https://api.so1.io/v1/control-plane/agents/execute', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.SO1_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(task)
      }).then(r => r.json())
    )
  );
  
  return executions.map(e => e.data.taskId);
}

const taskIds = await executeBatch([
  { agentId: 'mintlify-author', taskType: 'create-agent-reference', context: {...} },
  { agentId: 'api-documenter', taskType: 'generate-openapi', context: {...} },
  { agentId: 'runbook-writer', taskType: 'create-runbook', context: {...} }
]);

Error Codes

Code	Description	Resolution
`AGENT_NOT_FOUND`	Agent ID does not exist	Check available agents at `/agents`
`INVALID_TASK_TYPE`	Task type not supported by agent	Review agent capabilities in metadata
`GATE_VALIDATION_FAILED`	FORGE gate requirements not met	Provide required stage outputs
`CONTEXT_VALIDATION_FAILED`	Missing or invalid context fields	Check agent input requirements
`TASK_TIMEOUT`	Execution exceeded timeout limit	Increase timeout or optimize task
`RATE_LIMIT_EXCEEDED`	Too many concurrent executions	Reduce concurrency or upgrade tier

See Error Reference for complete error handling guide.

Agent Reference

Complete specifications for all 20 agents

FORGE Stages

6-stage execution model and gate validation

Workflows API

Trigger and manage n8n workflows

Orchestration API

Multi-agent coordination and dependencies

API Reference

Control Plane API

Veritas API

n8n API

Overview

Available Agents

Execute Agent

Endpoint

Request Body

Example Request

Response

Get Task Status

Endpoint

Path Parameters

Example Request

Response

List Agent Executions

Endpoint

Query Parameters

Example Request

Response

Cancel Task

Endpoint

Path Parameters

Request Body

Example Request

Response

Get Agent Metadata

Endpoint

Example Request

Response

Common Patterns

Polling for Completion

Batch Agent Execution

Error Codes

Agent Reference

FORGE Stages

Workflows API

Orchestration API

API Reference

Control Plane API

Veritas API

n8n API

​Overview

​Available Agents

​Execute Agent

​Endpoint

​Request Body

​Example Request

​Response

​Get Task Status

​Endpoint

​Path Parameters

​Example Request

​Response

​List Agent Executions

​Endpoint

​Query Parameters

​Example Request

​Response

​Cancel Task

​Endpoint

​Path Parameters

​Request Body

​Example Request

​Response

​Get Agent Metadata

​Endpoint

​Example Request

​Response

​Common Patterns

​Polling for Completion

​Batch Agent Execution

​Error Codes

​Related Resources

Agent Reference

FORGE Stages

Workflows API

Orchestration API

Overview

Available Agents

Execute Agent

Endpoint

Request Body

Example Request

Response

Get Task Status

Endpoint

Path Parameters

Example Request

Response

List Agent Executions

Endpoint

Query Parameters

Example Request

Response

Cancel Task

Endpoint

Path Parameters

Request Body

Example Request

Response

Get Agent Metadata

Endpoint

Example Request

Response

Common Patterns

Polling for Completion

Batch Agent Execution

Error Codes

Related Resources