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>",
  "trigger": {
    "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"
}

POST

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>",
  "trigger": {
    "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. For one_time automations with scope set to program, you can optionally include participant_id to target a specific participant. This sends the event to that participant rather than to the program at large. 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)

Show child attributes

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, has_counter)

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, has_counter)

guard_condition

string

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

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

List automations Get an automation

Documentation Index

Authorizations

Path Parameters

Body

Response