Workflows API

Create, manage, and execute automated multi-step workflows that orchestrate multiple AI agents to accomplish complex tasks.

Base URL

https://api.faosx.ai/v1/workflows

Workflow Object

A workflow defines a sequence of steps executed by one or more agents.

interface Workflow {
  id: string;                    // Unique identifier (e.g., "wfl_abc123")
  workspace_id: string;          // Parent workspace
  name: string;                  // Display name
  description?: string;          // Optional description
  status: WorkflowStatus;        // draft, active, paused, archived

  // Definition
  trigger: Trigger;              // How workflow starts
  steps: Step[];                 // Ordered workflow steps

  // Configuration
  settings: {
    timeout_seconds: number;     // Max execution time
    retry_policy: RetryPolicy;
    error_handling: ErrorHandling;
  };

  // Metadata
  created_at: string;
  updated_at: string;
  last_executed_at: string;

  // Statistics
  stats: {
    total_executions: number;
    success_rate: number;
    avg_duration_seconds: number;
  };
}

type WorkflowStatus = "draft" | "active" | "paused" | "archived";

interface Step {
  id: string;
  name: string;
  type: "agent_action" | "condition" | "parallel" | "wait" | "webhook";
  agent_id?: string;             // For agent_action steps
  config: Record<string, any>;   // Step-specific configuration
  next_step_id?: string;         // Sequential flow
  on_error?: string;             // Error handler step
}

interface Trigger {
  type: "manual" | "webhook" | "schedule" | "event";
  config: Record<string, any>;
}

Create Workflow

Create a new workflow.

POST /v1/workflows

Request Body

{
  "name": "Customer Onboarding",
  "description": "Automated customer onboarding workflow",
  "status": "draft",

  "trigger": {
    "type": "webhook",
    "config": {
      "path": "/onboard-customer"
    }
  },

  "steps": [
    {
      "id": "step_1",
      "name": "Verify Customer Info",
      "type": "agent_action",
      "agent_id": "agt_verification",
      "config": {
        "action": "verify_identity",
        "input_mapping": {
          "customer_data": "{{trigger.payload}}"
        }
      },
      "next_step_id": "step_2"
    },
    {
      "id": "step_2",
      "name": "Check Verification Result",
      "type": "condition",
      "config": {
        "condition": "{{step_1.result.verified}} === true",
        "if_true": "step_3",
        "if_false": "step_error"
      }
    },
    {
      "id": "step_3",
      "name": "Create Account",
      "type": "agent_action",
      "agent_id": "agt_operations",
      "config": {
        "action": "create_account",
        "input_mapping": {
          "customer_id": "{{step_1.result.customer_id}}"
        }
      },
      "next_step_id": "step_4"
    },
    {
      "id": "step_4",
      "name": "Send Welcome Email",
      "type": "agent_action",
      "agent_id": "agt_communications",
      "config": {
        "action": "send_email",
        "template": "welcome",
        "input_mapping": {
          "to": "{{trigger.payload.email}}",
          "account_id": "{{step_3.result.account_id}}"
        }
      }
    },
    {
      "id": "step_error",
      "name": "Handle Verification Failure",
      "type": "agent_action",
      "agent_id": "agt_support",
      "config": {
        "action": "create_support_ticket",
        "priority": "high"
      }
    }
  ],

  "settings": {
    "timeout_seconds": 300,
    "retry_policy": {
      "max_attempts": 3,
      "backoff_multiplier": 2
    },
    "error_handling": "continue"
  }
}

Response

{
  "data": {
    "id": "wfl_abc123",
    "workspace_id": "ws_xyz789",
    "name": "Customer Onboarding",
    "status": "draft",
    "trigger": { ... },
    "steps": [ ... ],
    "settings": { ... },
    "created_at": "2025-12-21T10:00:00Z",
    "updated_at": "2025-12-21T10:00:00Z",
    "last_executed_at": null,
    "stats": {
      "total_executions": 0,
      "success_rate": 0,
      "avg_duration_seconds": 0
    }
  }
}

Retrieve Workflow

Get details of a specific workflow.

GET /v1/workflows/{workflow_id}

Example Request

curl https://api.faosx.ai/v1/workflows/wfl_abc123 \
  -H "Authorization: Bearer sk_live_abc123..."

List Workflows

List all workflows in your workspace.

GET /v1/workflows

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `active`, `paused`
`limit`	integer	Results per page (default: 20, max: 100)
`starting_after`	string	Cursor for pagination

Example Request

curl "https://api.faosx.ai/v1/workflows?status=active" \
  -H "Authorization: Bearer sk_live_abc123..."

Update Workflow

Update an existing workflow.

PATCH /v1/workflows/{workflow_id}

Request Body

{
  "status": "active",
  "settings": {
    "timeout_seconds": 600
  }
}

Delete Workflow

Delete a workflow.

DELETE /v1/workflows/{workflow_id}

Execute Workflow

Manually trigger a workflow execution.

POST /v1/workflows/{workflow_id}/execute

Request Body

{
  "input": {
    "customer_id": "cus_abc123",
    "email": "customer@example.com",
    "name": "Jane Doe"
  },
  "wait_for_completion": false
}

Parameters

Parameter	Type	Required	Description
`input`	object	Yes	Input data for the workflow
`wait_for_completion`	boolean	No	Wait for result (default: false)

Synchronous Response (wait_for_completion: true)

{
  "data": {
    "execution_id": "wex_abc123",
    "workflow_id": "wfl_abc123",
    "status": "completed",
    "steps_completed": 4,
    "steps_total": 4,
    "result": {
      "account_id": "acc_xyz789",
      "welcome_email_sent": true
    },
    "duration_seconds": 12.4,
    "created_at": "2025-12-21T10:30:00Z",
    "completed_at": "2025-12-21T10:30:12.4Z"
  }
}

Asynchronous Response (wait_for_completion: false)

{
  "data": {
    "execution_id": "wex_abc123",
    "workflow_id": "wfl_abc123",
    "status": "running",
    "created_at": "2025-12-21T10:30:00Z"
  }
}

Get Execution Status

Check the status of a workflow execution.

GET /v1/workflows/{workflow_id}/executions/{execution_id}

Response

{
  "data": {
    "execution_id": "wex_abc123",
    "workflow_id": "wfl_abc123",
    "status": "running",
    "current_step": "step_3",
    "steps_completed": 2,
    "steps_total": 4,

    "step_results": [
      {
        "step_id": "step_1",
        "status": "completed",
        "result": {
          "verified": true,
          "customer_id": "cus_abc123"
        },
        "duration_ms": 342
      },
      {
        "step_id": "step_2",
        "status": "completed",
        "result": {
          "condition_met": true
        },
        "duration_ms": 5
      },
      {
        "step_id": "step_3",
        "status": "running",
        "started_at": "2025-12-21T10:30:05Z"
      }
    ],

    "created_at": "2025-12-21T10:30:00Z"
  }
}

Execution Statuses

Status	Description
`running`	Workflow is executing
`awaiting_approval`	Paused for human approval
`completed`	Successfully finished
`failed`	Execution failed
`cancelled`	Manually cancelled
`timeout`	Exceeded timeout limit

List Executions

List all executions for a workflow.

GET /v1/workflows/{workflow_id}/executions

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status
`limit`	integer	Results per page (default: 20)

Cancel Execution

Cancel a running workflow execution.

POST /v1/workflows/{workflow_id}/executions/{execution_id}/cancel

Response

{
  "data": {
    "execution_id": "wex_abc123",
    "status": "cancelled",
    "cancelled_at": "2025-12-21T10:35:00Z"
  }
}

Workflow Templates

FAOS provides pre-built workflow templates for common use cases.

List Templates

GET /v1/workflows/templates

Response

{
  "data": [
    {
      "id": "tmpl_customer_onboarding",
      "name": "Customer Onboarding",
      "description": "Automated customer onboarding with verification",
      "industry": "fintech",
      "steps_count": 5,
      "avg_duration_seconds": 15
    },
    {
      "id": "tmpl_support_escalation",
      "name": "Support Ticket Escalation",
      "description": "Multi-tier support escalation workflow",
      "industry": "all",
      "steps_count": 4,
      "avg_duration_seconds": 30
    }
  ]
}

Create from Template

POST /v1/workflows/from-template

Request Body

{
  "template_id": "tmpl_customer_onboarding",
  "name": "My Customer Onboarding",
  "customizations": {
    "agents": {
      "verification": "agt_my_verification_agent",
      "operations": "agt_my_ops_agent"
    },
    "settings": {
      "timeout_seconds": 600
    }
  }
}

Step Types

Agent Action

Execute an action using an AI agent.

{
  "type": "agent_action",
  "agent_id": "agt_abc123",
  "config": {
    "action": "process_refund",
    "input_mapping": {
      "order_id": "{{trigger.payload.order_id}}",
      "amount": "{{trigger.payload.amount}}"
    }
  }
}

Condition

Branch workflow based on a condition.

{
  "type": "condition",
  "config": {
    "condition": "{{step_1.result.amount}} > 100",
    "if_true": "step_approval",
    "if_false": "step_auto_process"
  }
}

Parallel

Execute multiple steps in parallel.

{
  "type": "parallel",
  "config": {
    "steps": ["step_notify_customer", "step_update_crm", "step_log_event"],
    "wait_for_all": true
  }
}

Wait

Pause workflow for a specified duration.

{
  "type": "wait",
  "config": {
    "duration_seconds": 3600,
    "reason": "Waiting for bank processing"
  }
}

Webhook

Call an external webhook.

{
  "type": "webhook",
  "config": {
    "url": "https://api.example.com/notify",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secrets.api_key}}"
    },
    "body": {
      "event": "workflow_completed",
      "data": "{{workflow.result}}"
    }
  }
}

Variable Interpolation

Reference data from previous steps using double curly braces:

Variable	Description	Example
`{{trigger.payload}}`	Input data	`{{trigger.payload.email}}`
`{{step_X.result}}`	Step result	`{{step_1.result.verified}}`
`{{workflow.execution_id}}`	Current execution	`{{workflow.execution_id}}`
`{{secrets.KEY}}`	Secret value	`{{secrets.api_key}}`

Code Examples

TypeScript/JavaScript

import { FAOS } from '@faosx/sdk';

const faos = new FAOS('sk_live_abc123...');

// Create workflow
const workflow = await faos.workflows.create({
  name: 'Customer Onboarding',
  trigger: { type: 'webhook' },
  steps: [
    {
      id: 'step_1',
      type: 'agent_action',
      agent_id: 'agt_verification',
      config: { action: 'verify_identity' }
    }
  ]
});

// Execute workflow
const execution = await faos.workflows.execute(workflow.id, {
  input: { customer_id: 'cus_123' },
  wait_for_completion: true
});

console.log(execution.result);

Python

from faosx import FAOS

faos = FAOS('sk_live_abc123...')

# Create workflow
workflow = faos.workflows.create(
    name='Customer Onboarding',
    trigger={'type': 'webhook'},
    steps=[
        {
            'id': 'step_1',
            'type': 'agent_action',
            'agent_id': 'agt_verification',
            'config': {'action': 'verify_identity'}
        }
    ]
)

# Execute workflow
execution = faos.workflows.execute(
    workflow.id,
    input={'customer_id': 'cus_123'},
    wait_for_completion=True
)

print(execution.result)

cURL

# Create workflow
curl -X POST https://api.faosx.ai/v1/workflows \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Onboarding",
    "trigger": {"type": "webhook"},
    "steps": [...]
  }'

# Execute workflow
curl -X POST https://api.faosx.ai/v1/workflows/wfl_abc123/execute \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"customer_id": "cus_123"},
    "wait_for_completion": false
  }'

Webhooks

Subscribe to workflow events:

workflow.created
workflow.updated
workflow.deleted
workflow.execution.started
workflow.execution.completed
workflow.execution.failed
workflow.execution.step_completed

See Webhooks API for details.

Errors

Common workflow-specific errors:

Error Code	HTTP Status	Description
`workflow_not_found`	404	Workflow ID doesn't exist
`invalid_step_config`	400	Step configuration invalid
`workflow_timeout`	408	Execution exceeded timeout
`step_failed`	500	Step execution failed
`circular_dependency`	400	Workflow has circular references

See Error Reference for all error codes.

Rate Limits

Endpoint	Limit
Create Workflow	20/hour
Execute Workflow	100/minute per workflow
All other endpoints	60/minute

Next Steps

Agents API - Manage AI agents
Webhooks - Real-time event notifications
Error Reference - Complete error documentation

Base URL​

Workflow Object​

Create Workflow​

Request Body​

Response​

Retrieve Workflow​

Example Request​

List Workflows​

Query Parameters​

Example Request​

Update Workflow​

Request Body​

Delete Workflow​

Execute Workflow​

Request Body​

Parameters​

Synchronous Response (wait_for_completion: true)​

Asynchronous Response (wait_for_completion: false)​

Get Execution Status​

Response​

Execution Statuses​

List Executions​

Query Parameters​

Cancel Execution​

Response​

Workflow Templates​

List Templates​

Response​

Create from Template​

Request Body​

Step Types​

Agent Action​

Condition​

Parallel​

Wait​

Webhook​

Variable Interpolation​

Code Examples​

TypeScript/JavaScript​

Python​

cURL​

Webhooks​

Errors​

Rate Limits​

Next Steps​

Base URL

Workflow Object

Create Workflow

Request Body

Response

Retrieve Workflow

Example Request

List Workflows

Query Parameters

Example Request

Update Workflow

Request Body

Delete Workflow

Execute Workflow

Request Body

Parameters

Synchronous Response (wait_for_completion: true)

Asynchronous Response (wait_for_completion: false)

Get Execution Status

Response

Execution Statuses

List Executions

Query Parameters

Cancel Execution

Response

Workflow Templates

List Templates

Response

Create from Template

Request Body

Step Types

Agent Action

Condition

Parallel

Wait

Webhook

Variable Interpolation

Code Examples

TypeScript/JavaScript

Python

cURL

Webhooks

Errors

Rate Limits

Next Steps