Skip to main content
POST
/
v1
/
programs
/
{programId}
/
automations
Create an automation
curl --request POST \
  --url https://api.scrip.dev/v1/programs/{programId}/automations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_name": "<string>",
  "name": "<string>",
  "scope": "program",
  "trigger": {
    "type": "cron",
    "cron_expression": "<string>",
    "schedule_config": {},
    "schedule_type": "<string>",
    "timezone": "<string>",
    "trigger_at": "2023-11-07T05:31:56Z"
  },
  "description": "<string>",
  "filter_hints": [
    {}
  ],
  "guard_condition": "<string>",
  "participant_filter": "<string>",
  "participant_id": "<string>",
  "payload": {}
}
'
{
  "created_at": "2023-11-07T05:31:56Z",
  "cron_expression": "<string>",
  "description": "<string>",
  "error_message": "<string>",
  "event_name": "<string>",
  "execution_completed_at": "2023-11-07T05:31:56Z",
  "execution_error": "<string>",
  "execution_started_at": "2023-11-07T05:31:56Z",
  "execution_status": "<string>",
  "filter_hints": [
    {}
  ],
  "guard_condition": "<string>",
  "id": "<string>",
  "last_error": "<string>",
  "last_evaluated_at": "2023-11-07T05:31:56Z",
  "last_run_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "next_run_at": "2023-11-07T05:31:56Z",
  "participant_filter": "<string>",
  "participant_id": "<string>",
  "participants_processed": 123,
  "participants_total": 123,
  "payload": {},
  "processed_at": "2023-11-07T05:31:56Z",
  "program_id": "<string>",
  "schedule_config": {},
  "schedule_type": "<string>",
  "scope": "<string>",
  "source": "<string>",
  "status": "<string>",
  "timezone": "<string>",
  "trigger_at": "2023-11-07T05:31:56Z",
  "trigger_type": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}
Creates an automation scoped to a program. At minimum you must provide name, trigger.type, scope, and event_name. The trigger.type can be cron, one_time, immediate, or participant_state. The scope determines whether the automation fires once at the program level or fans out across individual participants. Not all trigger and scope combinations are valid. The immediate and participant_state trigger types only support participants scope. If you specify an invalid combination, the request will be rejected with a validation error. When the automation fires, it generates an event with the specified event_name and optional payload. That event enters the rules engine like any other event, so you can attach rule logic to it without additional wiring.
For usage patterns and examples, see the Automations guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

​
programId
string<uuid>
required

Program ID

Body

application/json

Automation configuration

​
event_name
string
required

The event name generated when this automation fires (1-255 chars)

Required string length: 1 - 255
​
name
string
required

Human-readable label for this automation (1-255 chars)

Required string length: 1 - 255
​
scope
enum<string>
required

Whether the automation fires once at the program level or fans out per participant: program or participants

Available options:
program,
participants
​
trigger
object
required

Trigger configuration (type, schedule, timing)

​
description
string

Optional human-readable description of what this automation does

​
filter_hints
object[]

Optimization hints for the participant filter (e.g., has_tag, has_attribute)

​
guard_condition
string

CEL expression evaluated at trigger time; skips the participant if false

​
participant_filter
string

CEL expression that determines which participants are enrolled (scope=participants only)

​
participant_id
string

Target participant for program-scoped one-time automations (scope=program, one_time trigger only)

​
payload
object

Custom data included in the generated event

Response

Automation created

​
created_at
string<date-time>

When this automation was created

​
cron_expression
string

Cron expression defining the recurring schedule (cron trigger only)

​
description
string

Optional human-readable description of what this automation does

​
error_message
string

Error message if the one-time automation failed

​
event_name
string

The event name generated when this automation fires

​
execution_completed_at
string<date-time>

When the current fan-out execution completed

​
execution_error
string

Error message if the fan-out execution failed

​
execution_started_at
string<date-time>

When the current fan-out execution started

​
execution_status
string

Current fan-out execution state: idle, pending, executing, completed, or failed (participant-scoped only)

​
filter_hints
object[]

Optimization hints for the participant filter (e.g., has_tag, has_attribute)

​
guard_condition
string

CEL expression evaluated at trigger time; skips the participant if false

​
id
string

Unique identifier for this automation

​
last_error
string

Error message from the most recent cron execution, if any (cron trigger only)

​
last_evaluated_at
string<date-time>

When participant filters were last evaluated (participant_state trigger only)

​
last_run_at
string<date-time>

When this automation last fired (cron trigger only)

​
name
string

Human-readable label for this automation

​
next_run_at
string<date-time>

When this automation will next fire (cron trigger only)

​
participant_filter
string

CEL expression that determines which participants are enrolled

​
participant_id
string

Target participant for program-scoped one-time automations

​
participants_processed
integer

Participants processed so far in the current fan-out run

​
participants_total
integer

Total participants to process in the current fan-out run

​
payload
object

Custom data included in the generated event

​
processed_at
string<date-time>

When this one-time automation was processed

​
program_id
string

The program this automation belongs to

​
schedule_config
object

Configuration for the schedule type (participant_state trigger only)

​
schedule_type
string

How participant subscriptions are scheduled: ATTRIBUTE_DATE, INTERVAL, CRON, or THRESHOLD (participant_state trigger only)

​
scope
string

Whether the automation fires once at the program level or fans out per participant: program or participants

​
source
string

How this automation was created: api or rule_action

​
status
string

Current state: active, paused, completed, failed, or archived

​
timezone
string

IANA timezone used for scheduling (e.g., America/New_York)

​
trigger_at
string<date-time>

When this automation is scheduled to fire (one_time trigger only, RFC 3339)

​
trigger_type
string

How this automation is triggered: cron, one_time, participant_state, or immediate

​
updated_at
string<date-time>

When this automation was last updated