Automation API Reference

Automation API - Reference

Complete API reference for automation endpoints, authentication, and request/response formats.

Authentication & Base URL

All API endpoints require JWT authentication and workspace isolation via headers.

Base URL

http://localhost:3001/api/automation-rules

Required 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

API endpoints are rate-limited to prevent abuse and ensure fair usage.

User Type	Requests/Minute	Burst Limit
Anonymous	10	15
Authenticated	60	100
Enterprise	300	500

When rate limit is exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when to retry.

Implementation Guide Architecture Overview Back to Main Guide

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

{ "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" } ] }

{ "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" }

{ "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 }

{ "totalRules": 25, "activeRules": 18, "inactiveRules": 7, "totalExecutions": 5420, "successfulExecutions": 5380, "failedExecutions": 40, "averageSuccessRate": 99.26, "rulesNeedingAttention": 2 }

{ "success": true, "conditionsPassed": true, "actionsExecuted": 2, "dryRun": true, "results": [ { "action": "SEND_EMAIL", "status": "success" }, { "action": "CREATE_TASK", "status": "success" } ] }

{ "triggered": 3, "results": [ { "ruleId": "uuid-1", "success": true }, { "ruleId": "uuid-2", "success": true }, { "ruleId": "uuid-3", "success": false, "error": "Email service unavailable" } ] }

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" }

User Type

Requests/Minute

Burst Limit

Anonymous

Authenticated

100

Enterprise

300

500