Coordination API

Endpoints for creating plans and executing workflows.

Plans

Create Plan

POST /api/v1/coordination/plans

Request:

{
  "alias": "document-processing",
  "description": "Process and analyze documents",
  "steps": [
    {
      "id": "extract",
      "type": "agent",
      "agent": "document-extractor",
      "input": {"document_id": "{{ input.document_id }}"}
    },
    {
      "id": "analyze",
      "type": "agent",
      "agent": "analyzer",
      "depends_on": ["extract"],
      "input": {"text": "{{ steps.extract.output.text }}"}
    }
  ]
}

Response:

{
  "data": {
    "id": "plan_xxx",
    "alias": "document-processing",
    "description": "Process and analyze documents",
    "steps": [...],
    "version": 1,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Get Plan

GET /api/v1/coordination/plans/{plan_id}

List Plans

GET /api/v1/coordination/plans

Update Plan

PUT /api/v1/coordination/plans/{plan_id}

Delete Plan

DELETE /api/v1/coordination/plans/{plan_id}

Generate Plan (AI)

POST /api/v1/coordination/plans/generate

Request:

{
  "goal": "Create a workflow to process customer orders",
  "constraints": {
    "require_human_approval": true,
    "max_steps": 10,
    "available_agents": ["validator", "payment", "shipping"]
  }
}

Response:

{
  "data": {
    "steps": [...],
    "description": "Order processing workflow with validation...",
    "estimated_duration": "5-10 minutes"
  }
}

Runs

Execute Plan

POST /api/v1/coordination/runs

Request:

{
  "plan_id": "plan_xxx",
  "input": {
    "document_id": "doc-123"
  },
  "adaptive": {
    "enabled": true,
    "max_revisions": 5
  }
}

Response:

{
  "data": {
    "id": "run_xxx",
    "plan_id": "plan_xxx",
    "status": "running",
    "current_step": "extract",
    "started_at": "2026-01-01T12:00:00Z"
  }
}

Get Run

GET /api/v1/coordination/runs/{run_id}

Response:

{
  "data": {
    "id": "run_xxx",
    "plan_id": "plan_xxx",
    "status": "completed",
    "steps": [
      {
        "id": "extract",
        "status": "completed",
        "started_at": "...",
        "completed_at": "...",
        "output": {...}
      }
    ],
    "output": {...},
    "started_at": "...",
    "completed_at": "..."
  }
}

List Runs

GET /api/v1/coordination/runs?plan_id={plan_id}&status={status}

Cancel Run

POST /api/v1/coordination/runs/{run_id}/cancel

Human Steps

Approve Step

POST /api/v1/coordination/runs/{run_id}/steps/{step_id}/approve

Request:

{
  "approved": true,
  "comment": "Looks good"
}

Submit Human Input

POST /api/v1/coordination/runs/{run_id}/steps/{step_id}/input

Request:

{
  "data": {
    "priority": "high",
    "notes": "Urgent processing required"
  }
}

Triggers

Create Trigger

POST /api/v1/coordination/triggers

Schedule trigger:

{
  "plan_id": "plan_xxx",
  "type": "schedule",
  "config": {
    "cron": "0 9 * * MON-FRI"
  },
  "input": {"type": "daily-report"}
}

Event trigger:

{
  "plan_id": "plan_xxx",
  "type": "event",
  "config": {
    "topic": "documents.uploaded"
  },
  "input_mapping": {
    "document_id": "{{ event.document_id }}"
  }
}

Webhook trigger:

{
  "plan_id": "plan_xxx",
  "type": "webhook",
  "config": {
    "path": "/webhooks/process",
    "method": "POST"
  }
}

List Triggers

GET /api/v1/coordination/triggers?plan_id={plan_id}

Delete Trigger

DELETE /api/v1/coordination/triggers/{trigger_id}

Step Types

Type	Description
agent	Execute via agent
human_approval	Yes/no approval gate
human_input	Collect form data
condition	If/else branching
parallel	Concurrent execution
wait	Wait for time/event
sub_plan	Nested plan execution
transform	Data transformation