Triggers & Creation

API reference for creating workflows and configuring event-based and scheduled triggers.

Create workflows with event-based or scheduled triggers that execute actions automatically.

List workflows

Retrieve all workflows for your organization.

GET /api/v1/workflows

Scope: events:manage

Query parameters

Parameter	Type	Required	Description
active	boolean	No	Filter by active status
triggerType	string	No	Filter by trigger type: event or scheduled

Response

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_abc123def456",
        "name": "Notify on email failure",
        "trigger": {
          "type": "event",
          "eventType": "email.failed"
        },
        "actions": [
          {
            "type": "fire_webhook",
            "config": {
              "url": "https://yourapp.com/alerts",
              "method": "POST"
            }
          }
        ],
        "active": true,
        "createdAt": "2026-04-01T10:00:00.000Z",
        "lastTriggeredAt": "2026-04-05T14:30:00.000Z"
      }
    ]
  }
}

curl

curl https://api.platformxe.com/api/v1/workflows \
  -H "x-api-key: pxk_live_your_api_key_here"

---

Create a workflow

Register a new workflow with trigger and action configuration.

POST /api/v1/workflows

Scope: events:manage

Request body

Field	Type	Required	Description
name	string	Yes	Display name for the workflow
trigger	object	Yes	Trigger configuration (see below)
trigger.type	string	Yes	event or scheduled
trigger.eventType	string	Conditional	Event type pattern. Required when type is event
trigger.cron	string	Conditional	Cron expression (UTC). Required when type is scheduled
actions	Array<object>	Yes	Actions to execute (see below)
conditions	object	No	Optional conditions to filter events before execution

Event matching

Event-based triggers support exact match and wildcard patterns:

Pattern	Matches
email.sent	Exact match on email.sent only
email.*	All email events: email.sent, email.failed, etc.
*	All events (not recommended for production)

Scheduled triggers

Scheduled triggers use standard 5-field cron expressions evaluated in UTC:

Expression	Schedule
0 9 * * *	Every day at 09:00 UTC
0 9 * * 1-5	Weekdays at 09:00 UTC
*/30 * * * *	Every 30 minutes
0 0 1 * *	First day of each month at midnight UTC

Action configuration

Each action has a type and a config object:

{
  "type": "send_notification",
  "config": {
    "channel": "email",
    "to": [{ "email": "admin@yourapp.com" }],
    "subject": "Alert: Email delivery failed",
    "html": "<p>An email failed to deliver. Check the dashboard for details.</p>"
  }
}

{
  "type": "fire_webhook",
  "config": {
    "url": "https://yourapp.com/automation/handler",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
}

{
  "type": "call_api",
  "config": {
    "url": "https://api.platformxe.com/api/v1/messaging/email/send",
    "method": "POST",
    "body": {
      "to": [{ "email": "ops@yourapp.com" }],
      "subject": "Scheduled report",
      "html": "<p>Your daily report is ready.</p>"
    }
  }
}

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

// Event-based workflow
const result = await px.workflows.create({
  name: 'Notify on email failure',
  trigger: {
    type: 'event',
    eventType: 'email.failed',
  },
  actions: [
    {
      type: 'fire_webhook',
      config: {
        url: 'https://yourapp.com/alerts',
        method: 'POST',
      },
    },
  ],
});

console.log(result.data.id);
// "wf_abc123def456"

// Scheduled workflow
const scheduled = await px.workflows.create({
  name: 'Daily usage report',
  trigger: {
    type: 'scheduled',
    cron: '0 9 * * 1-5', // Weekdays at 09:00 UTC
  },
  actions: [
    {
      type: 'call_api',
      config: {
        url: 'https://api.platformxe.com/api/v1/messaging/email/send',
        method: 'POST',
        body: {
          to: [{ email: 'ops@yourapp.com' }],
          subject: 'Daily Usage Report',
          html: '<p>Your daily usage report is ready.</p>',
        },
      },
    },
  ],
});

Error responses

Code	Description
BAD_REQUEST	Missing required fields, invalid cron expression, or invalid event pattern
FORBIDDEN	API key does not have the events:manage scope
RATE_LIMITED	Rate limit exceeded for this API key