> ## 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. # Triggers API > Manage workflow triggers programmatically with the Kaie API ## Triggers API The Triggers API allows you to create, manage, and monitor workflow triggers. Triggers are events that automatically start your workflows, such as incoming messages, scheduled times, or external webhooks. ## List Triggers Retrieve a list of all triggers in your account. ### Request ```http theme={null} GET /v1/triggers ``` ### Parameters | Parameter | Type | Description | | ------------- | ------- | ---------------------------------------------------------------- | | `page` | integer | Page number (default: 1) | | `limit` | integer | Items per page (default: 20, max: 100) | | `type` | string | Filter by trigger type (`message`, `schedule`, `webhook`, `api`) | | `status` | string | Filter by status (`active`, `inactive`, `paused`) | | `workflow_id` | string | Filter by workflow ID | ### Response ```json theme={null} { "data": [ { "id": "trigger-123", "name": "WhatsApp Support Trigger", "type": "message", "status": "active", "workflow_id": "workflow-456", "channel": "whatsapp", "configuration": { "keywords": ["help", "support", "question"], "case_sensitive": false }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z", "execution_count": 250, "last_triggered": "2024-01-25T09:15:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 15, "pages": 1 } } ``` ## Get Trigger Retrieve details of a specific trigger. ### Request ```http theme={null} GET /v1/triggers/{trigger_id} ``` ### Response ```json theme={null} { "data": { "id": "trigger-123", "name": "WhatsApp Support Trigger", "type": "message", "status": "active", "workflow_id": "workflow-456", "channel": "whatsapp", "configuration": { "keywords": ["help", "support", "question"], "case_sensitive": false, "exact_match": false, "language": "en" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-20T14:45:00Z", "execution_count": 250, "last_triggered": "2024-01-25T09:15:00Z" } } ``` ## Create Trigger Create a new trigger for a workflow. ### Request ```http theme={null} POST /v1/triggers ``` ### Request Body ```json theme={null} { "name": "Instagram Marketing Trigger", "type": "message", "workflow_id": "workflow-789", "channel": "instagram", "configuration": { "keywords": ["promo", "discount", "sale"], "case_sensitive": false, "exact_match": false, "language": "en" } } ``` ### Response ```json theme={null} { "data": { "id": "trigger-456", "name": "Instagram Marketing Trigger", "type": "message", "status": "active", "workflow_id": "workflow-789", "channel": "instagram", "configuration": { "keywords": ["promo", "discount", "sale"], "case_sensitive": false, "exact_match": false, "language": "en" }, "created_at": "2024-01-25T11:00:00Z", "updated_at": "2024-01-25T11:00:00Z", "execution_count": 0, "last_triggered": null } } ``` ## Update Trigger Update an existing trigger. ### Request ```http theme={null} PUT /v1/triggers/{trigger_id} ``` ### Request Body ```json theme={null} { "name": "Updated Instagram Marketing Trigger", "configuration": { "keywords": ["promo", "discount", "sale", "offer"], "case_sensitive": false, "exact_match": false, "language": "en" } } ``` ### Response ```json theme={null} { "data": { "id": "trigger-456", "name": "Updated Instagram Marketing Trigger", "type": "message", "status": "active", "workflow_id": "workflow-789", "channel": "instagram", "configuration": { "keywords": ["promo", "discount", "sale", "offer"], "case_sensitive": false, "exact_match": false, "language": "en" }, "created_at": "2024-01-25T11:00:00Z", "updated_at": "2024-01-25T12:00:00Z", "execution_count": 0, "last_triggered": null } } ``` ## Delete Trigger Delete a trigger permanently. ### Request ```http theme={null} DELETE /v1/triggers/{trigger_id} ``` ### Response ```json theme={null} { "message": "Trigger deleted successfully" } ``` ## Trigger Types ### Message Triggers Trigger workflows based on incoming messages. #### Configuration ```json theme={null} { "type": "message", "configuration": { "keywords": ["help", "support", "question"], "case_sensitive": false, "exact_match": false, "language": "en", "channel": "whatsapp" } } ``` #### Parameters | Parameter | Type | Description | | ---------------- | ------- | ---------------------------------- | | `keywords` | array | List of keywords to match | | `case_sensitive` | boolean | Whether matching is case sensitive | | `exact_match` | boolean | Whether to match exact phrases | | `language` | string | Language code for matching | | `channel` | string | Communication channel to monitor | ### Schedule Triggers Trigger workflows at specific times or intervals. #### Configuration ```json theme={null} { "type": "schedule", "configuration": { "cron_expression": "0 9 * * 1-5", "timezone": "UTC", "start_date": "2024-01-01T00:00:00Z", "end_date": "2024-12-31T23:59:59Z" } } ``` #### Parameters | Parameter | Type | Description | | ----------------- | ------ | ------------------------------ | | `cron_expression` | string | Cron expression for scheduling | | `timezone` | string | Timezone for the schedule | | `start_date` | string | When to start the schedule | | `end_date` | string | When to end the schedule | ### Webhook Triggers Trigger workflows from external webhooks. #### Configuration ```json theme={null} { "type": "webhook", "configuration": { "url": "https://api.kaie.ai/v1/webhooks/trigger-123", "secret": "webhook-secret-key", "method": "POST", "headers": { "X-Custom-Header": "value" } } } ``` #### Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------- | | `url` | string | Webhook URL for this trigger | | `secret` | string | Secret for webhook verification | | `method` | string | HTTP method for webhook | | `headers` | object | Custom headers for webhook | ### API Triggers Trigger workflows via direct API calls. #### Configuration ```json theme={null} { "type": "api", "configuration": { "endpoint": "/v1/triggers/trigger-123/fire", "authentication": "api_key", "rate_limit": 100 } } ``` #### Parameters | Parameter | Type | Description | | ---------------- | ------- | --------------------------- | | `endpoint` | string | API endpoint for triggering | | `authentication` | string | Authentication method | | `rate_limit` | integer | Rate limit per hour | ## Trigger Management ### Activate Trigger Activate a trigger to start monitoring for events. ### Request ```http theme={null} POST /v1/triggers/{trigger_id}/activate ``` ### Response ```json theme={null} { "data": { "id": "trigger-123", "status": "active", "activated_at": "2024-01-25T11:00:00Z" } } ``` ### Deactivate Trigger Deactivate a trigger to stop monitoring for events. ### Request ```http theme={null} POST /v1/triggers/{trigger_id}/deactivate ``` ### Response ```json theme={null} { "data": { "id": "trigger-123", "status": "inactive", "deactivated_at": "2024-01-25T12:00:00Z" } } ``` ### Pause Trigger Temporarily pause a trigger without deactivating it. ### Request ```http theme={null} POST /v1/triggers/{trigger_id}/pause ``` ### Response ```json theme={null} { "data": { "id": "trigger-123", "status": "paused", "paused_at": "2024-01-25T12:30:00Z" } } ``` ### Resume Trigger Resume a paused trigger. ### Request ```http theme={null} POST /v1/triggers/{trigger_id}/resume ``` ### Response ```json theme={null} { "data": { "id": "trigger-123", "status": "active", "resumed_at": "2024-01-25T13:00:00Z" } } ``` ## Trigger Executions ### List Trigger Executions Get a list of trigger executions. ### Request ```http theme={null} GET /v1/triggers/{trigger_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", "trigger_id": "trigger-123", "workflow_id": "workflow-456", "status": "success", "triggered_at": "2024-01-25T10:30:00Z", "completed_at": "2024-01-25T10:30:15Z", "duration_ms": 15000, "input": { "message": "I need help with my order", "customer_id": "customer-789", "channel": "whatsapp" }, "output": { "workflow_execution_id": "workflow-execution-123" } } ], "pagination": { "page": 1, "limit": 20, "total": 50, "pages": 3 } } ``` ### Get Trigger Execution Details Get detailed information about a specific trigger execution. ### Request ```http theme={null} GET /v1/triggers/{trigger_id}/executions/{execution_id} ``` ### Response ```json theme={null} { "data": { "id": "execution-789", "trigger_id": "trigger-123", "workflow_id": "workflow-456", "status": "success", "triggered_at": "2024-01-25T10:30:00Z", "completed_at": "2024-01-25T10:30:15Z", "duration_ms": 15000, "input": { "message": "I need help with my order", "customer_id": "customer-789", "channel": "whatsapp", "metadata": { "user_agent": "WhatsApp/2.23.1.74", "timestamp": "2024-01-25T10:30:00Z" } }, "output": { "workflow_execution_id": "workflow-execution-123", "workflow_status": "success" }, "error": null } } ``` ## Trigger Analytics ### Get Trigger Metrics Retrieve analytics data for a specific trigger. ### Request ```http theme={null} GET /v1/triggers/{trigger_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": { "trigger_id": "trigger-123", "period": { "start_date": "2024-01-01T00:00:00Z", "end_date": "2024-01-31T23:59:59Z" }, "metrics": { "total_executions": 250, "successful_executions": 240, "failed_executions": 10, "success_rate": 0.96, "average_duration_ms": 5000, "unique_customers": 150, "channel_breakdown": { "whatsapp": 200, "instagram": 50 } }, "daily_metrics": [ { "date": "2024-01-01", "executions": 8, "success_rate": 0.95, "average_duration_ms": 4800 } ] } } ``` ## Error Handling ### Common Error Codes | Status Code | Error Code | Description | | ----------- | -------------------------- | ------------------------------------- | | 400 | `INVALID_TRIGGER_CONFIG` | Trigger configuration is invalid | | 400 | `MISSING_REQUIRED_FIELD` | Required field is missing | | 404 | `TRIGGER_NOT_FOUND` | Trigger does not exist | | 409 | `TRIGGER_ALREADY_EXISTS` | Trigger with this name already exists | | 422 | `INVALID_CRON_EXPRESSION` | Cron expression is invalid | | 500 | `TRIGGER_EXECUTION_FAILED` | Trigger execution failed | ### Error Response Format ```json theme={null} { "error": { "code": "INVALID_TRIGGER_CONFIG", "message": "Trigger configuration is invalid", "details": "Keywords array cannot be empty", "field": "configuration.keywords" } } ``` ## Rate Limiting Trigger 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 workflows programmatically Access analytics data Set up webhook integrations Learn about API authentication