Sign in

v2

latestOpenAPI 3.1.12026-07-2613060964.2 KB

Create or Update Workflow

Create a new workflow or update the draft version of an existing one

post/v1/{workspace}/workflow/{slug}/

Path parameters

workspacestring required

Workspace where the workflow should be created (staging, production, etc.)

slugstring required

Unique identifier of the workflow. You can get it from workflow settings for existing workflows.

Query parameters

commitboolean

Whether to commit the workflow immediately. Workflow will be successfully committed only if validation_result.is_valid is true.

commit_messagestring

Commit message describing the changes (required if commit=true)

Request body

namestring required

Human-readable name of the workflow. Workflow slug is generated from this name for new workflows.

descriptionstring nullable

Description explaining the usecase of the workflow

is_enabledboolean

Whether the workflow should be enabled

categorystring required

Notification category of the workflow. Used to apply category-specific settings and preferences.

tagsstring[]

Tags are used for grouping and filtering workflows in list.

trigger_type'event' | 'api' required

You can trigger a workflow either via API by passing its slug directly, or through an event-based system where the workflow runs when a specific event occurs. You can compare both methods here. If the workflow should run when a user enters or exits a list, use trigger_type = event.

trigger_eventsstring[]

Events that trigger this workflow (required if trigger_type = event). In case of list entry/exit, event names will be $USER_ENTERED_LIST - <list_id> and $USER_EXITED_LIST - <list_id> respectively.

override_recipients_type'user' | 'single_object_fields'

Override recipients using a property from the trigger payload. Type defines if the workflow should run for a list of users or a single object. Only applicable for trigger_type = event.

override_recipients_user_exprstring nullable

JQ expression to override recipients when override_recipients_type = user. Only applicable for trigger_type = event.

override_actor_user_exprstring nullable

JQ expression to override actor. Only applicable for trigger_type = event.

override_tenant_exprstring nullable

JQ expression to override tenant. Only applicable for trigger_type = event.

Example request

{
  "name": "Welcome Sequence",
  "category": "transactional",
  "payload_schema": {
    "schema": "onboarding-sequence-schema",
    "version_no": 1
  },
  "ratelimit": {
    "count": 4,
    "sliding_window": "6m"
  },
  "conditions": [
    {
      "type": "expression_v1",
      "expression_v1": {
        "args": [
          {
            "op": "==",
            "value": "\"admin\"",
            "variable": "role",
            "variable_ns": "$recipient"
          }
        ]
      }
    }
  ],
  "override_recipients_type": "user",
  "override_recipients_user_expr": ".distinct_id",
  "override_recipients_single_object_fields_expr": {
    "id": ".object_id",
    "object_type": ".object_type",
    "$object_subscriptions_query.depth": "2"
  },
  "override_actor_user_expr": ".actor_id",
  "override_tenant_expr": ".tenant_id",
  "tree": {
    "nodes": [
      {
        "name": "Wait 30 minutes",
        "relative_to": {
          "pivot_expr": ".start_time"
        }
      }
    ]
  }
}

Response

The response includes the same workflow object as input along with a validation_result field that indicates whether the workflow configuration is valid.