Automation API - Reference
Complete API reference for automation endpoints, authentication, and request/response formats.
Authentication & Base URL
Base URL
http://localhost:3001/api/automation-rulesRequired Headers
| Header | Value | Description |
|---|---|---|
Authorization | Bearer <JWT_TOKEN> | JWT token from authentication |
x-workspace-id | <WORKSPACE_UUID> | Current workspace identifier for multi-tenant isolation |
Content-Type | application/json | Required for POST/PUT requests |
API Endpoints
1. List All Rules
GET
/api/automation-rules
Retrieve all automation rules for the current workspace.
Response (200)
{
"rules": [
{
"id": "uuid",
"name": "High Score Lead Notification",
"trigger": "LEAD_SCORE_THRESHOLD",
"conditions": [...],
"actions": [...],
"isActive": true,
"executionCount": 142,
"successCount": 140,
"failureCount": 2,
"lastSuccessAt": "2024-01-15T10:30:00Z"
}
]
}2. Get Single Rule
GET
/api/automation-rules/:id
Retrieve a specific automation rule by ID.
Response (200)
{
"id": "uuid",
"name": "High Score Lead Notification",
"description": "Send email when lead score exceeds 70",
"trigger": "LEAD_SCORE_THRESHOLD",
"conditions": [
{
"field": "score",
"operator": "greater_than",
"value": 70
}
],
"actions": [
{
"type": "SEND_EMAIL",
"config": {
"to": "sales@company.com",
"subject": "High Score Lead Alert",
"template": "high-score-lead"
}
}
],
"isActive": true,
"workspaceId": "workspace-uuid"
}3. Create Rule
POST
/api/automation-rules
Create a new automation rule.
Request Body
{
"name": "New Lead Welcome Email",
"description": "Send welcome email to new leads",
"trigger": "LEAD_CREATED",
"conditions": [
{
"field": "status",
"operator": "equals",
"value": "new"
}
],
"actions": [
{
"type": "SEND_EMAIL",
"config": {
"to": "{{lead.email}}",
"subject": "Welcome!",
"template": "welcome-email"
}
},
{
"type": "CREATE_TASK",
"config": {
"title": "Follow up with {{lead.name}}",
"dueIn": "24h"
}
}
],
"isActive": true
}4. Update Rule
PUT
/api/automation-rules/:id
Update an existing automation rule.
Request Body (partial update)
{
"name": "Updated Rule Name",
"isActive": false
}5. Delete Rule
DELETE
/api/automation-rules/:id
Delete an automation rule permanently.
Response (204)
No content (successful deletion)6. Toggle Rule Active Status
PATCH
/api/automation-rules/:id/toggle
Toggle a rule's active status (enable/disable).
Response (200)
{
"id": "uuid",
"isActive": false
}7. Clone Rule
POST
/api/automation-rules/:id/clone
Create a duplicate of an existing rule (inactive by default).
Response (201)
{
"id": "new-uuid",
"name": "Copy of High Score Lead Notification",
"isActive": false,
...
}8. Get Health Report
GET
/api/automation-rules/health
Get health statistics for all automation rules.
Response (200)
{
"totalRules": 25,
"activeRules": 18,
"inactiveRules": 7,
"totalExecutions": 5420,
"successfulExecutions": 5380,
"failedExecutions": 40,
"averageSuccessRate": 99.26,
"rulesNeedingAttention": 2
}9. Get Rules Needing Attention
GET
/api/automation-rules/attention
Get rules with recent failures or high failure rates.
Response (200)
{
"rules": [
{
"id": "uuid",
"name": "Failing Rule",
"failureCount": 15,
"lastError": "Network timeout",
"lastFailureAt": "2024-01-15T12:00:00Z"
}
]
}10. Manual Execute Rule
POST
/api/automation-rules/:id/execute
Manually trigger a rule with test data (dry run or real execution).
Request Body
{
"data": {
"leadId": "uuid",
"score": 85
},
"dryRun": true
}Response (200)
{
"success": true,
"conditionsPassed": true,
"actionsExecuted": 2,
"dryRun": true,
"results": [
{
"action": "SEND_EMAIL",
"status": "success"
},
{
"action": "CREATE_TASK",
"status": "success"
}
]
}11. Trigger Rules by Event
POST
/api/automation-rules/trigger/:eventType
Trigger all rules matching a specific event type.
Example: POST /api/automation-rules/trigger/LEAD_CREATED
{
"data": {
"leadId": "uuid",
"name": "John Doe",
"email": "john@example.com",
"score": 65,
"status": "new"
}
}Response (200)
{
"triggered": 3,
"results": [
{
"ruleId": "uuid-1",
"success": true
},
{
"ruleId": "uuid-2",
"success": true
},
{
"ruleId": "uuid-3",
"success": false,
"error": "Email service unavailable"
}
]
}Error Codes
| Code | Description | Response |
|---|---|---|
400 | Bad Request - Invalid input | { "error": "Invalid trigger type" } |
401 | Unauthorized - Missing or invalid JWT | { "error": "Authentication required" } |
403 | Forbidden - Insufficient permissions | { "error": "Access denied" } |
404 | Not Found - Rule doesn't exist | { "error": "Automation rule not found" } |
422 | Validation Error - Invalid data format | { "errors": [{ "field": "name", "message": "Required" }] } |
500 | Server Error - Internal failure | { "error": "Internal server error" } |
Rate Limiting
| User Type | Requests/Minute | Burst Limit |
|---|---|---|
| Anonymous | 10 | 15 |
| Authenticated | 60 | 100 |
| Enterprise | 300 | 500 |
Retry-After header indicating when to retry.