> ## Documentation Index > Fetch the complete documentation index at: https://docs.kaie.ai/llms.txt > Use this file to discover all available pages before exploring further. # Workflows API > Manage workflows programmatically with the Kaie API ## Workflows API The Workflows API allows you to create, read, update, and delete workflows programmatically. You can also manage workflow executions, monitor performance, and control workflow states. ## List Workflows Retrieve a list of all workflows in your account. ### Request ```http theme={null} GET /v1/workflows ``` ### Parameters | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------ | | `page` | integer | Page number (default: 1) | | `limit` | integer | Items per page (default: 20, max: 100) | | `status` | string | Filter by status (`active`, `inactive`, `draft`) | | `channel` | string | Filter by communication channel | | `search` | string | Search workflows by name or description | ### Response ```json theme={null} { "data": [ { "id": "workflow-123", "name": "Customer Support Bot", "description": "Automated customer support workflow", "status": "active", "channel": "whatsapp", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z", "execution_count": 1250, "success_rate": 0.95 } ], "pagination": { "page": 1, "limit": 20, "total": 50, "pages": 3 } } ``` ## Get Workflow Retrieve details of a specific workflow. ### Request ```http theme={null} GET /v1/workflows/{workflow_id} ``` ### Response ```json theme={null} { "data": { "id": "workflow-123", "name": "Customer Support Bot", "description": "Automated customer support workflow", "status": "active", "channel": "whatsapp", "configuration": { "trigger": { "type": "message", "keywords": ["help", "support", "question"] }, "nodes": [ { "id": "node-1", "type": "message", "content": "Hi! How can I help you today?", "next": "node-2" }, { "id": "node-2", "type": "ai_response", "knowledge_base": "support-kb", "next": "node-3" } ] }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z", "execution_count": 1250, "success_rate": 0.95 } } ``` ## Create Workflow Create a new workflow. ### Request ```http theme={null} POST /v1/workflows ``` ### Request Body ```json theme={null} { "name": "New Customer Onboarding", "description": "Welcome new customers and collect information", "channel": "whatsapp", "configuration": { "trigger": { "type": "message", "keywords": ["start", "begin", "new"] }, "nodes": [ { "id": "welcome", "type": "message", "content": "Welcome! Let's get you started.", "next": "collect_info" }, { "id": "collect_info", "type": "form", "fields": [ { "name": "name", "type": "text", "required": true, "label": "What's your name?" } ], "next": "confirmation" } ] } } ``` ### Response ```json theme={null} { "data": { "id": "workflow-456", "name": "New Customer Onboarding", "description": "Welcome new customers and collect information", "status": "draft", "channel": "whatsapp", "created_at": "2024-01-25T09:15:00Z", "updated_at": "2024-01-25T09:15:00Z", "execution_count": 0, "success_rate": null } } ``` ## Update Workflow Update an existing workflow. ### Request ```http theme={null} PUT /v1/workflows/{workflow_id} ``` ### Request Body ```json theme={null} { "name": "Updated Customer Onboarding", "description": "Enhanced welcome flow for new customers", "configuration": { "trigger": { "type": "message", "keywords": ["start", "begin", "new", "welcome"] }, "nodes": [ { "id": "welcome", "type": "message", "content": "Welcome to our platform! Let's get you started.", "next": "collect_info" } ] } } ``` ### Response ```json theme={null} { "data": { "id": "workflow-456", "name": "Updated Customer Onboarding", "description": "Enhanced welcome flow for new customers", "status": "draft", "channel": "whatsapp", "created_at": "2024-01-25T09:15:00Z", "updated_at": "2024-01-25T10:30:00Z", "execution_count": 0, "success_rate": null } } ``` ## Delete Workflow Delete a workflow permanently. ### Request ```http theme={null} DELETE /v1/workflows/{workflow_id} ``` ### Response ```json theme={null} { "message": "Workflow deleted successfully" } ``` ## Activate Workflow Activate a workflow to start processing messages. ### Request ```http theme={null} POST /v1/workflows/{workflow_id}/activate ``` ### Response ```json theme={null} { "data": { "id": "workflow-123", "status": "active", "activated_at": "2024-01-25T11:00:00Z" } } ``` ## Deactivate Workflow Deactivate a workflow to stop processing messages. ### Request ```http theme={null} POST /v1/workflows/{workflow_id}/deactivate ``` ### Response ```json theme={null} { "data": { "id": "workflow-123", "status": "inactive", "deactivated_at": "2024-01-25T12:00:00Z" } } ``` ## Workflow Executions ### List Executions Get a list of workflow executions. ### Request ```http theme={null} GET /v1/workflows/{workflow_id}/executions ``` ### Parameters | Parameter | Type | Description | | ------------ | ------- | ------------------------------------------------- | | `page` | integer | Page number (default: 1) | | `limit` | integer | Items per page (default: 20, max: 100) | | `status` | string | Filter by status (`success`, `failed`, `running`) | | `start_date` | string | Filter executions after this date (ISO 8601) | | `end_date` | string | Filter executions before this date (ISO 8601) | ### Response ```json theme={null} { "data": [ { "id": "execution-789", "workflow_id": "workflow-123", "status": "success", "started_at": "2024-01-25T10:30:00Z", "completed_at": "2024-01-25T10:30:15Z", "duration_ms": 15000, "customer_id": "customer-456", "channel": "whatsapp", "input": { "message": "I need help with my order" }, "output": { "response": "I'd be happy to help with your order. What's your order number?", "next_action": "wait_for_input" } } ], "pagination": { "page": 1, "limit": 20, "total": 150, "pages": 8 } } ``` ### Get Execution Details Get detailed information about a specific execution. ### Request ```http theme={null} GET /v1/workflows/{workflow_id}/executions/{execution_id} ``` ### Response ```json theme={null} { "data": { "id": "execution-789", "workflow_id": "workflow-123", "status": "success", "started_at": "2024-01-25T10:30:00Z", "completed_at": "2024-01-25T10:30:15Z", "duration_ms": 15000, "customer_id": "customer-456", "channel": "whatsapp", "steps": [ { "node_id": "welcome", "type": "message", "status": "completed", "started_at": "2024-01-25T10:30:00Z", "completed_at": "2024-01-25T10:30:02Z", "duration_ms": 2000, "input": { "message": "I need help with my order" }, "output": { "message_sent": "Hi! How can I help you today?" } }, { "node_id": "ai_response", "type": "ai_response", "status": "completed", "started_at": "2024-01-25T10:30:02Z", "completed_at": "2024-01-25T10:30:15Z", "duration_ms": 13000, "input": { "message": "I need help with my order" }, "output": { "response": "I'd be happy to help with your order. What's your order number?", "confidence": 0.95 } } ], "input": { "message": "I need help with my order" }, "output": { "response": "I'd be happy to help with your order. What's your order number?", "next_action": "wait_for_input" } } } ``` ## Workflow Analytics ### Get Workflow Metrics Retrieve analytics data for a specific workflow. ### Request ```http theme={null} GET /v1/workflows/{workflow_id}/metrics ``` ### Parameters | Parameter | Type | Description | | ------------- | ------ | ------------------------------------------------- | | `start_date` | string | Start date for metrics (ISO 8601) | | `end_date` | string | End date for metrics (ISO 8601) | | `granularity` | string | Data granularity (`hour`, `day`, `week`, `month`) | ### Response ```json theme={null} { "data": { "workflow_id": "workflow-123", "period": { "start_date": "2024-01-01T00:00:00Z", "end_date": "2024-01-31T23:59:59Z" }, "metrics": { "total_executions": 1250, "successful_executions": 1187, "failed_executions": 63, "success_rate": 0.95, "average_duration_ms": 12000, "total_messages_sent": 2500, "total_messages_received": 1250, "unique_customers": 450, "channel_breakdown": { "whatsapp": 800, "instagram": 300, "voice": 150 } }, "daily_metrics": [ { "date": "2024-01-01", "executions": 45, "success_rate": 0.96, "average_duration_ms": 11500 } ] } } ``` ## Error Handling ### Common Error Codes | Status Code | Error Code | Description | | ----------- | --------------------------- | -------------------------------------- | | 400 | `INVALID_WORKFLOW_CONFIG` | Workflow configuration is invalid | | 400 | `MISSING_REQUIRED_FIELD` | Required field is missing | | 404 | `WORKFLOW_NOT_FOUND` | Workflow does not exist | | 409 | `WORKFLOW_ALREADY_EXISTS` | Workflow with this name already exists | | 422 | `INVALID_NODE_CONFIG` | Node configuration is invalid | | 500 | `WORKFLOW_EXECUTION_FAILED` | Workflow execution failed | ### Error Response Format ```json theme={null} { "error": { "code": "INVALID_WORKFLOW_CONFIG", "message": "Workflow configuration is invalid", "details": "Node 'welcome' is missing required field 'content'", "field": "configuration.nodes[0].content" } } ``` ## Rate Limiting Workflow API endpoints are subject to rate limiting: * **List/Get operations**: 1000 requests per hour * **Create/Update operations**: 100 requests per hour * **Delete operations**: 50 requests per hour * **Execution operations**: 500 requests per hour ## Next Steps Explore more API endpoints: Manage workflow triggers Access analytics data Set up webhook integrations Learn about API authentication