Workflows API

Workflow management endpoints

Complete API reference for creating, managing, and executing multi-agent workflows with MotteAF.

Workflow Management

POST

/api/workflows/create

Create a new workflow with nodes, edges, and configuration.

Request Body

{
  "name": "Customer Support Workflow",
  "description": "Automated customer inquiry processing",
  "version": "1.0",
  "nodes": [
    {
      "id": "classifier",
      "type": "llm_agent",
      "position": {"x": 100, "y": 100},
      "config": {
        "model": "gpt-4",
        "prompt": "Classify this customer inquiry: {{input}}",
        "temperature": 0.1,
        "max_tokens": 100
      }
    },
    {
      "id": "responder",
      "type": "llm_agent", 
      "position": {"x": 300, "y": 100},
      "config": {
        "model": "gpt-4",
        "prompt": "Generate a helpful response for this {{classifier.category}} inquiry: {{input}}",
        "temperature": 0.7,
        "max_tokens": 200
      }
    }
  ],
  "edges": [
    {
      "id": "edge1",
      "from": "classifier",
      "to": "responder",
      "condition": "classifier.category != 'spam'"
    }
  ],
  "settings": {
    "timeout": 300,
    "retry_attempts": 3,
    "parallel_limit": 5
  }
}

Response

{
  "workflow_id": "wf_abc123",
  "name": "Customer Support Workflow",
  "status": "created",
  "version": "1.0",
  "created_at": "2024-01-15T10:30:00Z",
  "nodes_count": 2,
  "edges_count": 1
}
GET

/api/workflows/{workflow_id}

Get workflow details, configuration, and current status.

Response

{
  "workflow_id": "wf_abc123",
  "name": "Customer Support Workflow",
  "description": "Automated customer inquiry processing",
  "version": "1.0",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z",
  "nodes": [...],
  "edges": [...],
  "settings": {
    "timeout": 300,
    "retry_attempts": 3,
    "parallel_limit": 5
  },
  "execution_stats": {
    "total_runs": 145,
    "success_rate": 0.94,
    "avg_duration": 2.3
  }
}
PUT

/api/workflows/{workflow_id}

Update workflow configuration, nodes, or edges.

Request Body

{
  "name": "Updated Customer Support Workflow",
  "description": "Enhanced automated customer inquiry processing",
  "nodes": [
    {
      "id": "classifier",
      "type": "llm_agent",
      "config": {
        "model": "gpt-4",
        "prompt": "Classify and prioritize this customer inquiry: {{input}}",
        "temperature": 0.1
      }
    }
  ],
  "settings": {
    "timeout": 600,
    "retry_attempts": 5
  }
}

Response

{
  "workflow_id": "wf_abc123",
  "status": "updated",
  "version": "1.1",
  "updated_at": "2024-01-15T12:00:00Z",
  "changes": [
    "Updated classifier prompt",
    "Increased timeout to 600s",
    "Increased retry attempts to 5"
  ]
}
DELETE

/api/workflows/{workflow_id}

Delete a workflow and all its execution history.

Response

{
  "workflow_id": "wf_abc123",
  "status": "deleted",
  "message": "Workflow and all execution history deleted successfully"
}

Workflow Execution

POST

/api/workflows/execute

Execute a workflow with input data and get results.

Request Body

{
  "workflow_id": "wf_abc123",
  "input": {
    "message": "I can't access my account and need help resetting my password",
    "customer_id": "cust_456",
    "priority": "medium"
  },
  "context": {
    "session_id": "sess_789",
    "channel": "email"
  },
  "options": {
    "async": false,
    "timeout": 300,
    "debug": false
  }
}

Response (Synchronous)

{
  "execution_id": "exec_def456",
  "workflow_id": "wf_abc123",
  "status": "completed",
  "result": {
    "classifier": {
      "category": "account_access",
      "priority": "high",
      "sentiment": "frustrated"
    },
    "responder": {
      "response": "I understand you're having trouble accessing your account. I'll help you reset your password right away. Please check your email for password reset instructions, which should arrive within 5 minutes. If you don't receive the email, please let me know and I can assist you further."
    }
  },
  "execution_time": 2.4,
  "tokens_used": 156,
  "cost": 0.0023,
  "started_at": "2024-01-15T14:30:00Z",
  "completed_at": "2024-01-15T14:30:02Z"
}

Response (Asynchronous)

{
  "execution_id": "exec_def456",
  "workflow_id": "wf_abc123",
  "status": "running",
  "message": "Workflow execution started",
  "started_at": "2024-01-15T14:30:00Z",
  "status_url": "/api/workflows/executions/exec_def456"
}
GET

/api/workflows/executions/{execution_id}

Get the status and results of a workflow execution.

Response

{
  "execution_id": "exec_def456",
  "workflow_id": "wf_abc123",
  "status": "completed",
  "progress": 1.0,
  "current_node": null,
  "result": {...},
  "execution_trace": [
    {
      "node_id": "classifier",
      "status": "completed",
      "started_at": "2024-01-15T14:30:00Z",
      "completed_at": "2024-01-15T14:30:01Z",
      "input": {...},
      "output": {...},
      "tokens_used": 45,
      "cost": 0.0008
    },
    {
      "node_id": "responder",
      "status": "completed",
      "started_at": "2024-01-15T14:30:01Z",
      "completed_at": "2024-01-15T14:30:02Z",
      "input": {...},
      "output": {...},
      "tokens_used": 111,
      "cost": 0.0015
    }
  ],
  "total_tokens": 156,
  "total_cost": 0.0023,
  "execution_time": 2.4
}

Node Types

Node TypePurposeRequired ConfigOutput Format
llm_agentGenerate text responsesmodel, promptstring
api_callExternal API integrationurl, methodobject
conditionConditional branchingconditionboolean
transformData transformationscriptany
memory_querySearch memory bankqueryarray
parallelParallel executionbranchesobject

Error Handling

WORKFLOW_NOT_FOUND

The specified workflow ID does not exist or is not accessible.

EXECUTION_TIMEOUT

Workflow execution exceeded the specified timeout limit.

NODE_EXECUTION_FAILED

A node in the workflow failed to execute successfully.

INVALID_WORKFLOW_SCHEMA

The workflow definition contains invalid nodes, edges, or configuration.