Workflows API

The Workflows API provides direct workflow execution, separate from the chat-based interaction. This allows programmatic execution of specific workflow templates with progress streaming.

Endpoints

Method	Endpoint	Description
GET	/api/v1/aim/workflows	List available workflows
GET	/api/v1/aim/workflows/revoked	List revoked workflows
GET	/api/v1/aim/workflows/{id}/steps	Get workflow steps and tools
GET	/api/v1/aim/workflows/{id}/queries	Related queries for a workflow
GET	/api/v1/aim/workflows/{id}/audit	Audit trail for a workflow
POST	/api/v1/aim/workflows/execute	Execute a workflow with input parameters
POST	/api/v1/aim/workflows/{id}/restore	Restore a revoked workflow
DELETE	/api/v1/aim/workflows/{id}	Revoke a workflow

---

Examples

List Workflows

curl "https://yourorg.squadai.uk/api/v1/aim/workflows?skip=0&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "workflows": [
    {
      "id": "wf-001",
      "name": "Fault Schedule Summary",
      "description": "Summarise active fault schedules for a given reactor unit",
      "category": "reporting",
      "status": "active",
      "created_at": "2026-03-10T08:00:00Z",
      "step_count": 4,
      "query_count": 3
    },
    {
      "id": "wf-002",
      "name": "Document Comparison",
      "description": "Compare two versions of a safety case document",
      "category": "analysis",
      "status": "active",
      "created_at": "2026-03-12T14:30:00Z",
      "step_count": 6,
      "query_count": 1
    }
  ],
  "total": 8,
  "skip": 0,
  "limit": 20
}

Get Workflow Steps

Inspect the individual steps and tools that make up a workflow.

curl https://yourorg.squadai.uk/api/v1/aim/workflows/wf-001/steps \
  -H "Authorization: Bearer $TOKEN"

Response 200

[
  {
    "id": "step-001",
    "name": "Classify Query",
    "description": "Determine query type and risk level",
    "step_number": 1,
    "tool_name": "classifier",
    "tool_description": "Classifies incoming queries by type"
  },
  {
    "id": "step-002",
    "name": "Retrieve Schedules",
    "description": "Fetch fault schedules from the knowledge graph",
    "step_number": 2,
    "tool_name": "retriever",
    "tool_description": "Executes Cypher queries against Neo4j"
  },
  {
    "id": "step-003",
    "name": "Summarise Results",
    "description": "Generate a natural-language summary",
    "step_number": 3,
    "tool_name": "summariser",
    "tool_description": "LLM-based summarisation of structured data"
  },
  {
    "id": "step-004",
    "name": "Format Output",
    "description": "Produce the final response with citations",
    "step_number": 4,
    "tool_name": "formatter",
    "tool_description": "Formats output with source references"
  }
]

Execute a Workflow

Trigger a workflow and receive progress updates via SSE.

curl -X POST https://yourorg.squadai.uk/api/v1/aim/workflows/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf-001",
    "inputs": {
      "unit_id": 3,
      "status_filter": "active"
    }
  }'

Response 200 — text/event-stream

{"timestamp": "2026-03-17T11:00:00Z", "event": "workflow_started", "data": {"workflow_id": "wf-001", "run_id": "run-xyz"}}
{"timestamp": "2026-03-17T11:00:01Z", "event": "step_started", "data": {"step": "Classify Query", "step_number": 1}}
{"timestamp": "2026-03-17T11:00:02Z", "event": "step_completed", "data": {"step": "Classify Query", "step_number": 1}}
{"timestamp": "2026-03-17T11:00:03Z", "event": "step_started", "data": {"step": "Retrieve Schedules", "step_number": 2}}
{"timestamp": "2026-03-17T11:00:05Z", "event": "tool_executed", "data": {"tool_name": "retriever", "success": true, "result_count": 3}}
{"timestamp": "2026-03-17T11:00:06Z", "event": "step_completed", "data": {"step": "Retrieve Schedules", "step_number": 2}}
{"timestamp": "2026-03-17T11:00:10Z", "event": "workflow_completed", "data": {"workflow_id": "wf-001", "run_id": "run-xyz"}}

Related Queries

curl "https://yourorg.squadai.uk/api/v1/aim/workflows/wf-001/queries?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "queries": [
    {
      "id": "q-d4e5f6",
      "text": "What are the active fault schedules for reactor unit 3?",
      "reuse_count": 12,
      "timestamp": "2026-03-15T08:00:00Z",
      "similarity": 0.94
    }
  ],
  "total_count": 3
}

Revoke a Workflow

curl -X DELETE https://yourorg.squadai.uk/api/v1/aim/workflows/wf-001 \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "id": "wf-001",
  "status": "revoked"
}

Restore a Revoked Workflow

curl -X POST https://yourorg.squadai.uk/api/v1/aim/workflows/wf-001/restore \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "id": "wf-001",
  "status": "restored"
}