Control Plane API

REST API reference for the Parallax control plane.

Base URL

https://your-control-plane.example.com/api

Local development:

http://localhost:8080/api

Authentication

API Key

Include in the Authorization header:

curl -H "Authorization: Bearer pk_live_abc123" \
  https://parallax.example.com/api/patterns

JWT Token

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://parallax.example.com/api/patterns

Patterns

List Patterns

GET /api/patterns

Query Parameters:

Parameter	Type	Description
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset
`search`	string	Search by name or description

Response:

{
  "patterns": [
    {
      "name": "content-classifier",
      "version": "1.0.0",
      "description": "Classify content using multi-agent voting",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get Pattern

GET /api/patterns/{name}

Query Parameters:

Parameter	Type	Description
`version`	string	Specific version (default: latest)

Response:

{
  "name": "content-classifier",
  "version": "1.0.0",
  "description": "Classify content using multi-agent voting",
  "definition": {
    "input": {
      "content": {
        "type": "string",
        "required": true
      }
    },
    "agents": {
      "capabilities": ["classification"],
      "min": 3
    },
    "aggregation": {
      "strategy": "voting",
      "method": "majority"
    },
    "output": {
      "category": "$vote.result",
      "confidence": "$vote.confidence"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "createdBy": "alice@example.com"
}

Create Pattern

POST /api/patterns

Request Body:

{
  "name": "content-classifier",
  "version": "1.0.0",
  "description": "Classify content using multi-agent voting",
  "definition": "name: content-classifier\nversion: 1.0.0\n..."
}

Or with YAML directly:

POST /api/patterns
Content-Type: application/x-yaml

name: content-classifier
version: 1.0.0
...

Response:

{
  "name": "content-classifier",
  "version": "1.0.0",
  "created": true
}

Update Pattern

PUT /api/patterns/{name}

Creates a new version if version is different.

Request Body:

{
  "version": "1.1.0",
  "description": "Updated classifier",
  "definition": "..."
}

Delete Pattern

DELETE /api/patterns/{name}

Query Parameters:

Parameter	Type	Description
`version`	string	Delete specific version (default: all)

Response:

{
  "deleted": true,
  "versionsRemoved": 3
}

List Pattern Versions

GET /api/patterns/{name}/versions

Response:

{
  "versions": [
    {
      "version": "1.0.0",
      "createdAt": "2024-01-10T10:00:00Z"
    },
    {
      "version": "1.1.0",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Executions

Execute Pattern

POST /api/patterns/{name}/execute

Query Parameters:

Parameter	Type	Description
`version`	string	Pattern version (default: latest)
`async`	boolean	Return immediately with execution ID

Request Body:

{
  "input": {
    "content": "Document to classify"
  },
  "options": {
    "timeout": 30000,
    "priority": "high",
    "metadata": {
      "requestId": "req_123"
    }
  }
}

Synchronous Response:

{
  "executionId": "exec_abc123",
  "status": "completed",
  "result": {
    "category": "technology",
    "confidence": 0.92
  },
  "duration": 2340,
  "agents": [
    {
      "id": "agent_1",
      "result": {"category": "technology", "confidence": 0.95}
    },
    {
      "id": "agent_2",
      "result": {"category": "technology", "confidence": 0.88}
    },
    {
      "id": "agent_3",
      "result": {"category": "technology", "confidence": 0.93}
    }
  ]
}

Async Response:

{
  "executionId": "exec_abc123",
  "status": "pending",
  "statusUrl": "/api/executions/exec_abc123"
}

Execute with Streaming

POST /api/patterns/{name}/execute/stream

Returns Server-Sent Events:

event: started
data: {"executionId": "exec_abc123", "status": "running"}

event: agent_result
data: {"agentId": "agent_1", "result": {"category": "technology"}}

event: agent_result
data: {"agentId": "agent_2", "result": {"category": "technology"}}

event: completed
data: {"status": "completed", "result": {"category": "technology", "confidence": 0.92}}

Get Execution

GET /api/executions/{executionId}

Response:

{
  "executionId": "exec_abc123",
  "pattern": {
    "name": "content-classifier",
    "version": "1.0.0"
  },
  "status": "completed",
  "input": {
    "content": "Document to classify"
  },
  "result": {
    "category": "technology",
    "confidence": 0.92
  },
  "startedAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:02Z",
  "duration": 2340,
  "agents": [...]
}

List Executions

GET /api/executions

Query Parameters:

Parameter	Type	Description
`pattern`	string	Filter by pattern name
`status`	string	Filter by status
`since`	string	ISO timestamp
`until`	string	ISO timestamp
`limit`	number	Max results
`offset`	number	Pagination offset

Response:

{
  "executions": [
    {
      "executionId": "exec_abc123",
      "pattern": "content-classifier",
      "status": "completed",
      "startedAt": "2024-01-15T10:30:00Z",
      "duration": 2340
    }
  ],
  "total": 1234,
  "limit": 20,
  "offset": 0
}

Cancel Execution

POST /api/executions/{executionId}/cancel

Response:

{
  "executionId": "exec_abc123",
  "status": "cancelled",
  "cancelledAt": "2024-01-15T10:30:05Z"
}

Retry Execution

POST /api/executions/{executionId}/retry

Creates a new execution with the same input.

Response:

{
  "originalExecutionId": "exec_abc123",
  "newExecutionId": "exec_xyz789",
  "status": "pending"
}

Agents

List Agents

GET /api/agents

Query Parameters:

Parameter	Type	Description
`status`	string	Filter: connected, disconnected
`capabilities`	string	Comma-separated capabilities
`region`	string	Filter by region

Response:

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "classification-agent-1",
      "status": "connected",
      "capabilities": ["classification", "analysis"],
      "region": "us-east-1",
      "connectedAt": "2024-01-15T08:00:00Z",
      "lastHeartbeat": "2024-01-15T10:30:00Z",
      "tasksCompleted": 1234,
      "metadata": {
        "model": "gpt-4",
        "version": "1.0.0"
      }
    }
  ],
  "total": 10,
  "connected": 9,
  "disconnected": 1
}

Get Agent

GET /api/agents/{agentId}

Response:

{
  "id": "agent_abc123",
  "name": "classification-agent-1",
  "status": "connected",
  "capabilities": ["classification", "analysis"],
  "region": "us-east-1",
  "connectedAt": "2024-01-15T08:00:00Z",
  "lastHeartbeat": "2024-01-15T10:30:00Z",
  "statistics": {
    "tasksCompleted": 1234,
    "tasksSucceeded": 1200,
    "tasksFailed": 34,
    "averageLatency": 1500,
    "uptime": 86400
  },
  "metadata": {
    "model": "gpt-4",
    "version": "1.0.0"
  }
}

Disconnect Agent

POST /api/agents/{agentId}/disconnect

Gracefully disconnect an agent.

Response:

{
  "id": "agent_abc123",
  "disconnected": true,
  "disconnectedAt": "2024-01-15T10:30:00Z"
}

Health

Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 86400
}

Detailed Health

GET /api/health?detailed=true

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 86400,
  "components": {
    "database": "healthy",
    "redis": "healthy",
    "agents": {
      "connected": 10,
      "healthy": 10
    }
  },
  "metrics": {
    "executionsTotal": 12345,
    "executionsActive": 5,
    "avgExecutionTime": 2340
  }
}

Readiness

GET /api/health/ready

Returns 200 if ready to accept traffic, 503 if not.

Liveness

GET /api/health/live

Returns 200 if process is running, 503 if not.

Metrics

Prometheus Metrics

GET /api/metrics

Returns Prometheus-formatted metrics:

# HELP parallax_executions_total Total executions
# TYPE parallax_executions_total counter
parallax_executions_total{pattern="content-classifier",status="completed"} 1234

# HELP parallax_execution_duration_seconds Execution duration
# TYPE parallax_execution_duration_seconds histogram
parallax_execution_duration_seconds_bucket{pattern="content-classifier",le="1"} 100
parallax_execution_duration_seconds_bucket{pattern="content-classifier",le="5"} 900
parallax_execution_duration_seconds_bucket{pattern="content-classifier",le="10"} 1200

# HELP parallax_agents_connected Connected agents
# TYPE parallax_agents_connected gauge
parallax_agents_connected{region="us-east-1"} 10

Batch Operations

Batch Execute

POST /api/batch/execute

Request Body:

{
  "pattern": "content-classifier",
  "inputs": [
    {"content": "Document 1"},
    {"content": "Document 2"},
    {"content": "Document 3"}
  ],
  "options": {
    "concurrency": 5,
    "stopOnError": false
  }
}

Response:

{
  "batchId": "batch_abc123",
  "status": "running",
  "total": 3,
  "completed": 0,
  "failed": 0,
  "statusUrl": "/api/batch/batch_abc123"
}

Get Batch Status

GET /api/batch/{batchId}

Response:

{
  "batchId": "batch_abc123",
  "status": "completed",
  "total": 3,
  "completed": 3,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "executionId": "exec_1",
      "status": "completed",
      "result": {"category": "tech"}
    },
    {
      "index": 1,
      "executionId": "exec_2",
      "status": "completed",
      "result": {"category": "sports"}
    },
    {
      "index": 2,
      "executionId": "exec_3",
      "status": "completed",
      "result": {"category": "politics"}
    }
  ]
}

Error Responses

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input: content is required",
    "details": {
      "field": "content",
      "reason": "required"
    }
  },
  "requestId": "req_abc123"
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists
`TIMEOUT`	408	Request timeout
`RATE_LIMITED`	429	Too many requests
`NO_AGENTS`	503	No agents available
`INTERNAL_ERROR`	500	Server error

Rate Limits

Default limits:

Endpoint	Limit
`POST /patterns/*/execute`	100/minute
`GET /*`	1000/minute
`POST /*`	200/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705316400

Pagination

List endpoints support pagination:

GET /api/executions?limit=20&offset=40

Response includes pagination info:

{
  "executions": [...],
  "total": 1234,
  "limit": 20,
  "offset": 40,
  "hasMore": true
}

Webhooks

See Webhooks for event notifications.

SDKs

TypeScript SDK - Official TypeScript client
Pattern SDK - Pattern building

Next Steps

Agent Protocol - WebSocket protocol
Webhooks - Event notifications
TypeScript SDK - SDK reference

Base URL​

Authentication​

API Key​

JWT Token​

Patterns​

List Patterns​

Get Pattern​

Create Pattern​

Update Pattern​

Delete Pattern​

List Pattern Versions​

Executions​

Execute Pattern​

Execute with Streaming​

Get Execution​

List Executions​

Cancel Execution​

Retry Execution​

Agents​

List Agents​

Get Agent​

Disconnect Agent​

Health​

Health Check​

Detailed Health​

Readiness​

Liveness​

Metrics​

Prometheus Metrics​

Batch Operations​

Batch Execute​

Get Batch Status​

Error Responses​

Error Format​

Error Codes​

Rate Limits​

Pagination​

Webhooks​

SDKs​

Next Steps​

Base URL

Authentication

API Key

JWT Token

Patterns

List Patterns

Get Pattern

Create Pattern

Update Pattern

Delete Pattern

List Pattern Versions

Executions

Execute Pattern

Execute with Streaming

Get Execution

List Executions

Cancel Execution

Retry Execution

Agents

List Agents

Get Agent

Disconnect Agent

Health

Health Check

Detailed Health

Readiness

Liveness

Metrics

Prometheus Metrics

Batch Operations

Batch Execute

Get Batch Status

Error Responses

Error Format

Error Codes

Rate Limits

Pagination

Webhooks

SDKs

Next Steps