Workflows API

Create and execute multi-agent workflow pipelines.

Endpoints

Method	Path	Description
GET	`/workflows`	List all workflows
POST	`/workflows`	Create a workflow
GET	`/workflows/{id}`	Get workflow details
PUT	`/workflows/{id}`	Update a workflow
DELETE	`/workflows/{id}`	Delete a workflow
POST	`/workflows/{id}/run`	Start a workflow run
GET	`/workflows/{id}/runs`	List runs for a workflow
GET	`/runs/{id}`	Get run status
POST	`/workflows/step`	Execute single step (legacy)

POST /workflows

Create a new workflow definition.

curl -X POST http://localhost:4200/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claims-pipeline",
    "description": "End-to-end claims processing",
    "steps": [
      {
        "name": "intake",
        "agent": {"ByName": "claims-intake-agent"},
        "prompt_template": "Process this claim: {{input}}",
        "mode": "Sequential",
        "timeout_secs": 120,
        "error_mode": "Fail",
        "output_var": "claim_data"
      },
      {
        "name": "validation",
        "agent": {"ByName": "policy-validator"},
        "prompt_template": "Validate coverage: {{claim_data}}",
        "mode": "Sequential",
        "timeout_secs": 60,
        "error_mode": {"Retry": {"max_retries": 2}},
        "output_var": "validation_result"
      },
      {
        "name": "routing",
        "agent": {"ById": "550e8400-e29b-41d4-a716-446655440000"},
        "prompt_template": "Route claim: {{validation_result}}",
        "mode": "Sequential",
        "timeout_secs": 30,
        "error_mode": "Skip"
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	No	Description
`steps`	array	Yes	Ordered step definitions

Step Definition

Field	Type	Required	Description
`name`	string	Yes	Step name
`agent`	object	Yes	Agent ref: `{"ByName": "..."}` or `{"ById": "uuid"}`
`prompt_template`	string	Yes	Template with `{{input}}` / `{{var}}` placeholders
`mode`	string	Yes	`Sequential`, `FanOut`, `Collect`, `Conditional`, `Loop`
`timeout_secs`	integer	Yes	Max execution time
`error_mode`	string/object	Yes	`Fail`, `Skip`, or `{"Retry": {"max_retries": N}}`
`output_var`	string	No	Variable name to store step output

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "claims-pipeline",
  "description": "End-to-end claims processing",
  "steps": [...],
  "created_at": "2026-06-04T10:00:00Z"
}

GET /workflows

curl http://localhost:4200/workflows

Response (200)

{
  "workflows": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "claims-pipeline",
      "description": "End-to-end claims processing",
      "steps": [...],
      "created_at": "2026-06-04T10:00:00Z"
    }
  ]
}

GET /workflows/{id}

curl http://localhost:4200/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response (200)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "claims-pipeline",
  "description": "End-to-end claims processing",
  "steps": [
    {
      "name": "intake",
      "agent": {"ByName": "claims-intake-agent"},
      "prompt_template": "Process this claim: {{input}}",
      "mode": "Sequential",
      "timeout_secs": 120,
      "error_mode": "Fail",
      "output_var": "claim_data"
    }
  ],
  "created_at": "2026-06-04T10:00:00Z"
}

PUT /workflows/{id}

Update an existing workflow definition.

curl -X PUT http://localhost:4200/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claims-pipeline-v2",
    "description": "Updated pipeline with fraud check",
    "steps": [...]
  }'

Response (200)

Updated workflow definition.

DELETE /workflows/{id}

curl -X DELETE http://localhost:4200/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response (204 No Content)

POST /workflows/{id}/run

Start a workflow execution with input.

curl -X POST http://localhost:4200/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run \
  -H "Content-Type: application/json" \
  -d '{"input": "New auto claim: rear-end collision on I-95, policy POL-2024-200"}'

Request Body

Field	Type	Required	Description
`input`	string	Yes	Initial input text for the workflow

Response (200)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workflow_name": "claims-pipeline",
  "input": "New auto claim: rear-end collision on I-95...",
  "state": "Completed",
  "step_results": [
    {"step": "intake", "output": "Claim data collected...", "duration_ms": 2300},
    {"step": "validation", "output": "Coverage confirmed...", "duration_ms": 1100},
    {"step": "routing", "output": "Routed to auto-collision queue", "duration_ms": 800}
  ],
  "output": "Claim #CLM-2026-042 created. Routed to adjuster queue: auto-collision-moderate.",
  "started_at": "2026-06-04T10:15:00Z",
  "completed_at": "2026-06-04T10:15:04Z"
}

Failed Run Response

{
  "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "state": "Failed",
  "step_results": [
    {"step": "intake", "output": "...", "duration_ms": 2100}
  ],
  "error": "Step 'validation' timed out after 60 seconds",
  "started_at": "2026-06-04T09:30:00Z",
  "completed_at": "2026-06-04T09:31:02Z"
}

GET /workflows/{id}/runs

List all runs for a workflow.

curl http://localhost:4200/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/runs

Response (200)

{
  "runs": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "state": "Completed",
      "started_at": "2026-06-04T10:15:00Z",
      "completed_at": "2026-06-04T10:15:04Z"
    }
  ]
}

GET /runs/{id}

Get detailed status of a specific run.

curl http://localhost:4200/runs/c3d4e5f6-a7b8-9012-cdef-123456789012

Response (200)

Full run status (same format as POST /workflows/{id}/run response).

Run States

State	Description
`Pending`	Run queued, not yet started
`Running`	Currently executing steps
`Completed`	All steps finished successfully
`Failed`	A step failed (based on error_mode)