API Reference

Overview

The SO1 platform provides comprehensive APIs for orchestrating AI agents, managing workflows, and integrating with automation infrastructure. This reference covers all public APIs across the platform.

Control Plane API

Core orchestration and agent management

Veritas API

Prompt library and chain management

n8n API

Workflow automation endpoints

API Architecture

The SO1 platform follows a microservices architecture with three core APIs:

Control Plane API

Base URL: https://control-plane.so1.io/api/v1 The Control Plane API is the primary orchestration layer, managing:

Agent lifecycle and execution
Workflow coordination
FORGE gate validation
System health and metrics

Veritas API

Base URL: https://veritas.so1.io/api/v1 Veritas manages the centralized prompt library:

Prompt versioning and retrieval
Chain architecture
Fragment management
A/B testing and optimization

n8n API

Base URL: https://n8n.so1.io/api/v1 n8n provides workflow automation capabilities:

Workflow creation and execution
Webhook management
Scheduled task orchestration
Integration management

Quick Start

1. Obtain API Keys

# Control Plane API Key
export CONTROL_PLANE_API_KEY="cp_live_..."

# Veritas API Key
export VERITAS_API_KEY="ver_live_..."

# n8n API Key
export N8N_API_KEY="n8n_..."

API keys can be generated in the SO1 Console under Settings → API Keys.

2. Make Your First Request

curl https://control-plane.so1.io/api/v1/workflows \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json"

3. Execute an Agent

curl -X POST https://control-plane.so1.io/api/v1/agents/workflow-architect/execute \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Design a webhook processing workflow with error handling",
    "config": {
      "temperature": 0.7,
      "max_tokens": 2000
    }
  }'

Response:

{
  "execution_id": "exec_5Xy9mPqRs",
  "agent_id": "workflow-architect",
  "status": "completed",
  "output": {
    "workflow_json": { ... },
    "recommendations": [ ... ]
  },
  "metrics": {
    "duration_ms": 2847,
    "tokens_used": 1523
  }
}

Core Concepts

Authentication

All APIs use Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication Guide for detailed information.

Request/Response Format

Content Type: application/json
Character Encoding: UTF-8
Date Format: ISO 8601 (e.g., 2026-03-10T15:30:00Z)
Response Envelope: All responses use a consistent structure

Success Response:

{
  "success": true,
  "data": { ... },
  "metadata": {
    "timestamp": "2026-03-10T15:30:00Z",
    "request_id": "req_abc123"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid workflow configuration",
    "details": { ... }
  },
  "metadata": {
    "timestamp": "2026-03-10T15:30:00Z",
    "request_id": "req_abc123"
  }
}

Rate Limits

Rate limits vary by API and authentication tier:

Tier	Control Plane	Veritas	n8n
Free	100/hour	50/hour	20/hour
Pro	1000/hour	500/hour	200/hour
Enterprise	10000/hour	5000/hour	2000/hour

See Rate Limits for details.

Error Handling

All errors follow a consistent format with HTTP status codes and error codes:

400 - Bad Request (validation errors)
401 - Unauthorized (invalid/missing API key)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource doesn’t exist)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error (unexpected failure)
503 - Service Unavailable (maintenance/overload)

See Error Reference for complete error code list.

API Versioning

SO1 APIs follow semantic versioning with the version in the URL path:

https://control-plane.so1.io/api/v1/...

Version Support Policy

Current Version: v1 (stable)
Support Period: 12 months after new version release
Deprecation Notice: 6 months before end-of-life
Breaking Changes: Only in major version updates

Version Migration

When a new major version is released:

Announcement: 6 months advance notice
Parallel Support: Both versions available for 12 months
Migration Guide: Detailed upgrade documentation
Deprecation Warnings: API responses include deprecation headers

SDKs and Libraries

TypeScript/Node.js

npm install @so1/sdk

Python

pip install so1-sdk

Go

go get github.com/so1-io/so1-sdk-go

REST API

Direct HTTP requests to any endpoint

SDK Quick Start

TypeScript
Python
Go

import { SO1Client } from '@so1/sdk';

const client = new SO1Client({
  apiKey: process.env.CONTROL_PLANE_API_KEY,
  environment: 'production'
});

// Execute agent
const result = await client.agents.execute('workflow-architect', {
  input: 'Design a webhook processing workflow'
});

console.log(result.output);

from so1 import SO1Client

client = SO1Client(
    api_key=os.environ['CONTROL_PLANE_API_KEY'],
    environment='production'
)

# Execute agent
result = client.agents.execute(
    agent_id='workflow-architect',
    input='Design a webhook processing workflow'
)

print(result.output)

package main

import (
    "github.com/so1-io/so1-sdk-go"
    "os"
)

func main() {
    client := so1.NewClient(so1.Config{
        APIKey: os.Getenv("CONTROL_PLANE_API_KEY"),
        Environment: "production",
    })

    result, err := client.Agents.Execute("workflow-architect", so1.ExecuteInput{
        Input: "Design a webhook processing workflow",
    })

    if err != nil {
        panic(err)
    }

    println(result.Output)
}

API Explorer

Interactive API documentation with live request testing:

Open API Explorer

Test all endpoints with your API keys in a secure, interactive environment

Features

Live Testing: Execute requests against production or staging
Code Generation: Auto-generate code in multiple languages
Request History: Save and replay previous requests
Environment Management: Switch between dev/staging/production
Authentication: Securely store and manage API keys

Common Use Cases

Use Case 1: Execute Multi-Agent Workflow

# Create orchestration workflow
curl -X POST https://control-plane.so1.io/api/v1/orchestration/workflows \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Development Pipeline",
    "agents": [
      {"agent_id": "hono-backend", "stage": "build"},
      {"agent_id": "railway-deployer", "stage": "deploy"}
    ],
    "forge_validation": true
  }'

# Monitor workflow progress
curl https://control-plane.so1.io/api/v1/orchestration/workflows/wf_abc123 \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}"

Use Case 2: Refine and Deploy Prompt

# Refine prompt
curl -X POST https://veritas.so1.io/api/v1/prompts/refine \
  -H "Authorization: Bearer ${VERITAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_id": "prompt_workflow_architect_v1.2",
    "refinement_goals": ["improve_consistency", "reduce_verbosity"]
  }'

# Deploy refined prompt
curl -X POST https://veritas.so1.io/api/v1/prompts/promote \
  -H "Authorization: Bearer ${VERITAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_id": "prompt_workflow_architect_v1.3",
    "environment": "production"
  }'

Use Case 3: Deploy n8n Workflow

# Import workflow
curl -X POST https://n8n.so1.io/api/v1/workflows \
  -H "X-N8N-API-KEY: ${N8N_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @workflow.json

# Activate workflow
curl -X PATCH https://n8n.so1.io/api/v1/workflows/{id} \
  -H "X-N8N-API-KEY: ${N8N_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

Support and Resources

API Status

Real-time status of all API services

Community

Ask questions and share feedback

Support

Contact technical support team

Next Steps

Read Authentication Guide

Learn about API key management and security best practicesAuthentication Guide →

Explore Endpoints

Browse complete endpoint documentation for each APIControl Plane API →

Try Interactive Examples

Test API calls in the API ExplorerOpen API Explorer →

Install SDK

Get started quickly with official SDKs for TypeScript, Python, and Go

Control Plane API

Veritas API

n8n API

​Overview

Control Plane API

Veritas API

n8n API

​API Architecture

​Control Plane API

​Veritas API

​n8n API

​Quick Start

​1. Obtain API Keys

​2. Make Your First Request

​3. Execute an Agent

​Core Concepts

​Authentication

​Request/Response Format

​Rate Limits

​Error Handling

​API Versioning

​Version Support Policy

​Version Migration

​SDKs and Libraries

TypeScript/Node.js

Python

Go

REST API

​SDK Quick Start

​API Explorer

Open API Explorer

​Features

​Common Use Cases

​Use Case 1: Execute Multi-Agent Workflow

​Use Case 2: Refine and Deploy Prompt

​Use Case 3: Deploy n8n Workflow

​Support and Resources

API Status

Community

Support

​Next Steps

Overview

API Architecture

Control Plane API

Veritas API

n8n API

Quick Start

1. Obtain API Keys

2. Make Your First Request

3. Execute an Agent

Core Concepts

Authentication

Request/Response Format

Rate Limits

Error Handling

API Versioning

Version Support Policy

Version Migration

SDKs and Libraries

SDK Quick Start

API Explorer

Features

Common Use Cases

Use Case 1: Execute Multi-Agent Workflow

Use Case 2: Refine and Deploy Prompt

Use Case 3: Deploy n8n Workflow

Support and Resources

Next Steps