> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or Update Workflow > Create a new workflow or update the draft version of an existing one ## OpenAPI ````yaml POST /v1/{workspace}/workflow/{slug}/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /v1/{workspace}/workflow/{slug}/: post: summary: Create or Update Workflow description: Create a new workflow or update the draft version of an existing one operationId: upsert-workflow parameters: - in: path name: workspace required: true schema: type: string description: >- Workspace where the workflow should be created (staging, production, etc.) - in: path name: slug required: true schema: type: string description: >- Unique identifier of the workflow. You can get it from workflow settings for existing workflows. - in: query name: commit schema: type: boolean default: false description: >- Whether to commit the workflow immediately. Workflow will be successfully committed only if validation_result.is_valid is true. - in: query name: commit_message schema: type: string description: Commit message describing the changes (required if commit=true) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateUpdate' examples: workflow_example: summary: Example workflow creation description: Example of creating a simple email workflow value: name: Welcome Email description: Sends welcome email to new users category: transactional tags: - welcome - onboarding tree: nodes: - name: Send Email node_type: send_email properties: template: welcome-email-template subject: Welcome to our platform! description: Send welcome email to new users responses: '201': description: >- The response includes the same workflow object as input along with a validation_result field that indicates whether the workflow configuration is valid. content: application/json: examples: workflow_example: summary: Example workflow creation description: Example of creating a simple email workflow value: name: Welcome Email description: Sends welcome email to new users category: transactional tags: - welcome - onboarding tree: nodes: - name: Send Email node_type: send_email properties: template: welcome-email-template subject: Welcome to our platform! description: Send welcome email to new users validation_result: is_valid: true errors: [] schema: type: object properties: validation_result: type: object properties: is_valid: type: boolean description: >- Whether the workflow configuration is valid and can be committed errors: type: array description: >- List of validation errors if the workflow is invalid and `is_valid` is false. items: type: string '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' security: - ServiceTokenAuth: [] servers: - url: https://management-api.suprsend.com x-codeSamples: - lang: cURL source: > curl -X POST "https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/" \ --header 'Authorization: ServiceToken ' \ --header 'Content-Type: application/json' \ --data '{ "name": "Welcome Email", "description": "Sends welcome email to new users", "category": "transactional", "tags": ["welcome", "onboarding"], "tree": { "nodes": [ { "name": "Send Email", "node_type": "send_email", "properties": { "template": "welcome-email-template", "subject": "Welcome to our platform!" }, "description": "Send welcome email to new users" } ] } }' components: schemas: WorkflowCreateUpdate: type: object required: - name - trigger_type - category - tree properties: name: type: string description: >- Human-readable name of the workflow. Workflow slug is generated from this name for new workflows. example: Welcome Sequence description: type: string nullable: true description: Description explaining the usecase of the workflow is_enabled: type: boolean default: true description: Whether the workflow should be enabled category: type: string description: >- Notification category of the workflow. Used to apply category-specific settings and preferences. example: transactional tags: type: array items: type: string description: Tags are used for grouping and filtering workflows in list. example: onboarding-sequence trigger_type: type: string enum: - event - api description: >- 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](https://docs.suprsend.com/docs/event-vs-api-trigger). If the workflow should run when a user enters or exits a list, use `trigger_type = event`. payload_schema: type: object nullable: true properties: schema: type: string description: >- Linked schema slug. You can create a schema via [Create Schema](/reference/create-schema) endpoint and then link it here. example: onboarding-sequence-schema version_no: type: integer description: >- Schema version number to link. By default, live version is always picked for validation example: 1 description: >- Schema to validate workflow api data structure. Used only when trigger_type = api. trigger_events: type: array items: type: string description: >- Events that trigger this workflow (required if trigger_type = event). In case of list entry/exit, event names will be `$USER_ENTERED_LIST - ` and `$USER_EXITED_LIST - ` respectively. ratelimit: type: object nullable: true description: >- Throttle settings for the workflow. This is used to limit the number of times a workflow can be executed per user in a given time period. properties: count: type: integer description: Maximum number of executions allowed within the sliding window example: 4 sliding_window: type: string description: >- Time window for rate limiting to be passed in format `00d00h00m00s`, d (days), h (hours), m (minutes), s (seconds). Rate limit is applied within this window. example: 6m conditions: type: array nullable: true description: >- Trigger Conditions. Workflow will be executed if any of the conditions in this array evaluate to true. items: type: object properties: type: type: string description: >- Type of condition expression. Currently only `expression_v1` is supported. example: expression_v1 enum: - expression_v1 expression_v1: type: object description: Expression object containing the condition logic properties: op: type: string description: >- Logical operator to combine conditions. Currently only `AND` is supported. enum: - AND args: type: array description: >- Array of conditions. Each condition is defined as key (variable) value. Refer to [how to construct a condition here](https://docs.suprsend.com/docs/branch#constructing-a-condition). items: type: object properties: op: type: string description: >- Comparison operator between variable and value. Refer to list of [comparison operators here](https://docs.suprsend.com/docs/branch#key-value-pair). example: '==' enum: - '==' - '!=' - '>' - < - '>=' - <= - EMPTY - NON_EMPTY - CONTAINS - NOT_CONTAINS - ARRAY_INTERSECTS - NOT_ARRAY_INTERSECTS - DATETIME_EQUALS - DATETIME_LT - DATETIME_GT value: type: string description: >- Value to compare against. Can add fixed value as ".." or variable in JSONNET format as data.. example: '"admin"' variable: type: string description: >- key from your trigger payload to compare the value against. Direct key name is passed here. example: role variable_ns: type: string description: >- Variable namespace (empty for data passed in trigger, `$recipient` for recipient or object subscription properties, `$tenant` for tenant properties) example: $recipient enum: - '' - $recipient - $tenant override_recipients_type: type: string description: >- 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](https://docs.suprsend.com/docs/objects). Only applicable for trigger_type = `event`. example: user enum: - user - single_object_fields override_recipients_user_expr: type: string nullable: true description: >- JQ expression to override recipients when override_recipients_type = `user`. Only applicable for trigger_type = `event`. example: .distinct_id override_recipients_single_object_fields_expr: type: object nullable: true description: >- JQ expression to override recipients with object when override_recipients_type = `single_object_fields`. Only applicable for trigger_type = `event`. properties: id: type: string description: JQ expression to extract object ID from trigger payload example: .object_id object_type: type: string description: >- JQ expression to extract object type from trigger payload. You can also pass fixed value as "..". example: .object_type $object_subscriptions_query.depth: type: string description: >- Depth [Optional] is used to specify how deep to traverse object subscriptions. `depth=0` would only send notification to object channels and not its subscribers, `depth=1` would fetch 1 level of subscriptions, `depth=2` (maximum) → Also fetches subscriptions of child objects, eg. teams -> team members>. example: '2' example: id: .object_id object_type: .object_type $object_subscriptions_query.depth: '2' override_actor_user_expr: type: string nullable: true description: >- JQ expression to override actor. Only applicable for trigger_type = `event`. example: .actor_id override_tenant_expr: type: string nullable: true description: >- JQ expression to override [tenant](https://docs.suprsend.com/docs/tenants). Only applicable for trigger_type = `event`. example: .tenant_id tree: type: object properties: nodes: type: array items: oneOf: - $ref: '#/components/schemas/DelayNode' - $ref: '#/components/schemas/BatchNode' - $ref: '#/components/schemas/DigestNode' - $ref: '#/components/schemas/HttpApiWebhookNode' - $ref: '#/components/schemas/HttpApiFetchNode' - $ref: '#/components/schemas/BranchWaitUntilNode' - $ref: '#/components/schemas/BranchNode' - $ref: '#/components/schemas/TransformNode' - $ref: '#/components/schemas/TimeWindowNode' - $ref: '#/components/schemas/SubscriberListOperationAddUserNode' - $ref: '#/components/schemas/SubscriberListOperationRemoveUserNode' - $ref: '#/components/schemas/ObjectOperationAddSubscriptionNode' - $ref: '#/components/schemas/ObjectOperationRemoveSubscriptionNode' - $ref: '#/components/schemas/UserUpdateNode' - $ref: '#/components/schemas/InvokeWorkflowNode' - $ref: '#/components/schemas/SendEmailNode' - $ref: '#/components/schemas/SendSmsNode' - $ref: '#/components/schemas/SendWhatsappNode' - $ref: '#/components/schemas/SendMobilePushNode' - $ref: '#/components/schemas/SendInboxNode' - $ref: '#/components/schemas/SendWebpushNode' - $ref: '#/components/schemas/SendSlackNode' - $ref: '#/components/schemas/SendMsTeamsNode' - $ref: '#/components/schemas/SendMultiChannelNode' - $ref: '#/components/schemas/SendSmartChannelRoutingNode' description: Array of nodes in the workflow tree structure. description: >- Node tree structure of the workflow. Contains the nodes array with all workflow nodes and their configuration. DelayNode: type: object description: >- [**Delay**](https://docs.suprsend.com/docs/delay): Pauses workflow execution for a specified duration. required: - node_type - name - delay_type properties: name: type: string description: Human-readable name of the node example: Wait 30 minutes description: type: string nullable: true description: Description of what this node does node_type: type: string const: delay delay_type: type: string enum: - fixed - dynamic - relative_to description: |- Type of delay. Determines how the duration is calculated. **Fixed**: Static duration added as XXdXXhXXmXXs. **Dynamic**: duration is passed as variable in your trigger payload in jq format. Eg. `.delay_duration`, `$recipient.delay_duration`, `$actor.delay_duration`, `$tenant.delay_duration`. **Relative to**: delay is relative to a future timestamp passed in your trigger payload. Eg. `.start_time` before 15m. duration: type: string description: Duration value. Required for 'fixed' and 'dynamic' delay types. examples: fixed_duration: summary: Fixed duration example value: 30s dynamic_duration: summary: Dynamic duration from trigger payload value: .delay_duration recipient_duration: summary: Dynamic duration from recipient properties value: $recipient.delay_duration relative_to: type: object description: >- Relative delay configuration. Required when delay_type is 'relative_to'. properties: pivot_expr: type: string description: >- (jq-expression) variable defining the future timestamp from trigger payload relative to which delay is calculated. example: .start_time offset_type: type: string enum: - before - after description: Whether offset is to be added or subtracted from pivot_expr. offset_value_type: type: string enum: - fixed - dynamic description: >- Defines if the offset value is fixed or dynamic. **Fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. **Dynamic**: offset is passed as variable in your trigger payload or recipient, tenant properties in jq format. Eg. `$recipient.reminder_offset` before meeting_start_time. offset_value: type: string description: Offset value examples: fixed_offset: summary: Fixed duration offset value: 15m dynamic_offset: summary: Dynamic offset from recipient properties value: $recipient.reminder_offset BatchNode: type: object description: >- [**Batch**](https://docs.suprsend.com/docs/batch): Batches incoming workflow triggers/events for a duration to send consolidated notifications. required: - node_type - name - mode - window_type properties: name: type: string description: Human-readable name of the node example: Batch notifications description: type: string nullable: true description: Description of what this node does node_type: type: string const: batch mode: type: string enum: - accumulate_all - flush_leading_item description: >- **accumulate_all**: All events are accumulated in the batch and notification is sent once after batch window closes. **flush_leading_item**: Notification is sent immediately for the first event in the batch and rest of the events are batched and sent after batch window closes. Eg. Send anomaly alert with first notification sent at the occurrence of first error and next alert sent after 30 minutes if there are further errors. window_type: type: string enum: - fixed - dynamic - relative_to description: >- Type of batching window. **fixed**: Static window duration added as XXdXXhXXmXXs. Eg. 30s, 1h, 1d. **dynamic**: Batch window duration is passed as variable in your trigger payload. Add the variable in jq format. Eg. `.window_duration`, `$recipient.batch_duration`, `$actor.window_duration`, `$tenant.window_duration`. **relative_to**: Batch window is relative to a future timestamp passed in your trigger payload. Eg. 15 m before `.task_end_time`. fixed_window: type: string description: >- Batch window when window_type is 'fixed'. Static batch window for all users. Format: XXdXXhXXmXXs. example: 30s dynamic_window_expr: type: string description: >- Batch window when window_type is 'dynamic'. jq-expression for deriving batch window duration at runtime. examples: trigger_payload: summary: From trigger payload value: .window_duration recipient_property: summary: From recipient properties value: $recipient.batch_duration actor_property: summary: From actor properties value: $actor.window_duration tenant_property: summary: From tenant properties value: $tenant.window_duration relative_to: type: object description: >- Batch window when window_type is 'relative_to'. Batch window is calculated relative to a future timestamp. properties: pivot_expr: type: string description: >- (jq-expression) variable defining the future timestamp from trigger payload relative to which batch window is calculated. examples: trigger_payload: summary: From trigger payload value: .start_time recipient_property: summary: From recipient properties value: $recipient.task_end_time offset_type: type: string enum: - before - after description: >- Whether offset is to be added or subtracted from pivot timestamp. offset_value_type: type: string enum: - fixed - dynamic description: >- Defines if the offset value is fixed or dynamic. **Fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. **Dynamic**: offset is passed as variable in your trigger payload or recipient, tenant properties in jq format. Eg. `$recipient.reminder_offset` before meeting_start_time. offset_value: type: string description: Offset value. examples: fixed_offset: summary: Fixed duration offset value: 15m dynamic_offset: summary: Dynamic offset from recipient properties value: $recipient.reminder_offset retain_count: type: integer minimum: 1 maximum: 100 description: >- Maximum number of items to retain after batch closes (1-100). The output variable set will have the latest or first n items based on the retain_order. retain_order: type: string enum: - first - last description: Retain items in this order when retain_count is specified. batch_key: type: string description: >- jq-expression used to group events into separate batches. For example, when sending batched notifications for comments on different documents, use `.document_id` as the batch key to ensure comments from different documents are not combined into the same batch. example: .document_id DigestNode: type: object description: >- [**Digest**](https://docs.suprsend.com/docs/digest): Batches and sends summary notifications at a recurring digest schedule. required: - node_type - name - schedule_type properties: name: type: string description: Human-readable name of the node example: Daily digest node_type: type: string const: digest description: type: string nullable: true description: Description of what this node does schedule_type: type: string enum: - static - dynamic description: >- Type of schedule. Determines if the schedule is static or dynamic. **static**: Schedule is fixed and will be used for all recipients. **dynamic**: Schedule is dynamic and will be computed at runtime using the `dynamic_schedule_expr`. dynamic_schedule_expr: type: string description: >- jq-expression for deriving dynamic digest schedule at runtime. Eg. `.digest_schedule` example: .digest_schedule schedule: $ref: '#/components/schemas/Schedule' retain_count: type: integer minimum: 1 maximum: 100 description: >- Maximum number of items to retain after digest closes (1-100). By default, 10 items are retained. retain_order: type: string enum: - first - last description: Retain items in this order when retain_count is specified. trigger_min_count: type: integer minimum: 1 description: >- Digest will be sent if number of triggers in the batch are greater than or equal to this count, else skipped. HttpApiWebhookNode: type: object description: >- [**Webhook**](https://docs.suprsend.com/docs/webhook): Makes an HTTP API request to an endpoint. required: - node_type - name - http_method - url properties: name: type: string description: Human-readable name of the node example: Notify internal CRM node_type: type: string const: httpapi_webhook description: type: string nullable: true description: Description of what this node does http_method: type: string enum: - GET - PUT - POST - PATCH - DELETE description: HTTP method of the API call. url: type: string format: uri description: >- Endpoint URL of the API call. You can add variables in JSONNET format. Eg. `"https://api.example.com/webhook?id="+data["$recipient"].id` example: https://api.example.com/webhook headers: type: array description: >- List of headers as key-value pairs. You can add variables in JSONNET format. Eg. `"Bearer"+data["$tenant"].api_key` items: type: object properties: key: type: string description: header key example: - '"Authorization"' - '"Content-Type"' value: type: string description: header value example: - '"Bearer "+data["$tenant"].api_key' - '"application/json"' body_content_type: type: string default: application/json description: Content type for the body. body: type: string description: JSONNET script to evaluate request body. query_params: type: array description: >- List of query parameters as key-value pairs. You can add variables in JSONNET format. Eg. `data["$recipient"].id` items: type: object properties: key: type: string description: Query Parameter Key value: type: string description: Query Parameter Value output_key: type: string description: >- Optional key to store the response body of API call. If not provided, the response will be appended at the root of the workflow payload. It's recommended to provide a unique key here to avoid overwriting existing data. HttpApiFetchNode: type: object description: >- [**Fetch**](https://docs.suprsend.com/docs/fetch): Fetches data from an API endpoint using GET method only. required: - node_type - name - http_method - url properties: name: type: string description: Human-readable name of the node example: Fetch user data node_type: type: string const: httpapi_fetch description: type: string nullable: true description: Description of what this node does http_method: type: string const: GET description: HTTP method to use. Only GET is supported for fetch operations. url: type: string description: Endpoint URL to fetch data from. example: https://api.example.com/data headers: type: array description: >- List of headers as key-value pairs. You can add variables in JSONNET format. Eg. `"Bearer"+data["$tenant"].api_key` items: type: object properties: key: type: string description: header key examples: authorization: summary: Authorization header value: '"Authorization"' content_type: summary: Content-Type header value: Content-Type value: type: string description: header value example: - '"Bearer "+data["$tenant"].api_key' - '"application/json"' query_params: type: array description: >- List of query parameters as key-value pairs. You can add variables in JSONNET format. Eg. `data["$recipient"].id` items: type: object properties: key: type: string description: Query Parameter Key examples: id_param: summary: ID parameter value: id name_param: summary: Name parameter value: name value: type: string description: Query Parameter Value examples: data_id: summary: Data ID from payload value: data.id recipient_name: summary: Recipient name from data value: data["$recipient"].name output_key: type: string description: >- Optional key to store the response of API call. If not provided, the response will be appended at the root of the workflow payload. It's recommended to provide a unique key here to avoid overwriting existing data. BranchWaitUntilNode: type: object description: >- [**Wait Until**](https://docs.suprsend.com/docs/wait-until): Waits until a condition is met or the maximum time is reached. Uses branch structure with conditions. required: - node_type - name - branches properties: name: type: string description: Human-readable name of the node example: Wait for approval node_type: type: string const: branch_waituntil description: type: string nullable: true description: Description of what this node does branches: type: array description: >- Array of branches with conditions to evaluate. Minimum 2 branches required. minItems: 2 maxItems: 2 items: type: object properties: name: type: string description: Name of the branch for identification. description: type: string description: Description of what this branch does. is_default: type: boolean description: >- Whether this is the default branch. In case of wait until, branch with condition->type as 'delay' (max time) should always be the default branch. conditions: type: array description: Array of conditions to evaluate for this branch. items: type: object properties: type: type: string enum: - future_event - delay description: Type of condition to evaluate. event_name: type: string description: >- Name of the future event to wait for. Eg. `"request_approved"` maxLength: 255 event_conditions: type: array description: >- Additional conditions to evaluate when the future event occurs. items: type: object properties: variable_ns: type: string description: >- Namespace for the variable on left-hand side of expression. allowed_values: - '': Default namespace (payload data) - $brand: tenant/brand properties - $actor: user properties of the actor - $recipient: user properties of the recipient - $future_event: Future event properties required: false variable: type: string description: Variable name on left-hand side of expression. required: true example: status op: type: string description: Comparison operator for the expression. allowed_values: - '==': Equal to - '!=': Not equal to - '>': Greater than - <: Less than - '>=': Greater than or equal to - <=: Less than or equal to - EMPTY: Empty - NON_EMPTY: Not empty - CONTAINS: Contains - NOT_CONTAINS: Does not contain - DATETIME_EQUALS: Date time equals - DATETIME_LT: Date time less than - DATETIME_GT: Date time greater than value: type: string description: Right-hand side operand. example: approved delay_properties: type: object description: >- Timeout value after which the branch will be executed. Required when condition->type is 'delay'. properties: delay_type: type: string enum: - fixed - dynamic - relative_to description: >- Type of delay calculation. **fixed**: Static duration added as XXdXXhXXmXXs. **dynamic**: duration is passed as variable in your trigger payload in jq format. Eg. `.delay_duration`, `$recipient.delay_duration`, `$actor.delay_duration`, `$tenant.delay_duration`. **relative_to**: delay is relative to a future timestamp passed in your trigger payload. Eg. `.start_time` before 15m. value: type: string description: >- Delay value. Required for 'fixed' and 'dynamic' delay types. examples: fixed_duration: summary: Fixed duration example value: 30s dynamic_duration: summary: Dynamic duration from trigger payload value: .delay_duration recipient_duration: summary: Dynamic duration from recipient properties value: $recipient.delay_duration relative_to: type: object description: >- Relative delay configuration. Required when delay_type is 'relative_to'. example: pivot_expr: .start_time offset_type: before offset_value_type: fixed offset_value: 15m properties: pivot_expr: type: string description: >- (jq-expression) variable defining the future timestamp from trigger payload relative to which delay is calculated. offset_type: type: string enum: - before - after description: Whether to add or subtract offset from pivot. offset_value_type: type: string enum: - fixed - dynamic description: >- How to determine offset value. **fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. **dynamic**: offset is passed as variable in your trigger payload or recipient, tenant properties in jq format. Eg. `$recipient.reminder_offset` before meeting_start_time. offset_value: type: string description: >- Offset value. Required for 'fixed' and 'dynamic' offset_value_types. examples: fixed_offset: summary: Fixed duration offset value: 15m dynamic_offset: summary: Dynamic offset from recipient properties value: $recipient.reminder_offset nodes: type: array description: >- Array of nodes to execute when this branch condition is met. Minimum 1 node required. BranchNode: type: object description: >- [**Branch**](https://docs.suprsend.com/docs/branch): Divides the workflow in different branches and executes the first branch that matches the branch condition. required: - node_type - name - branches properties: name: type: string description: Human-readable name of the node example: Check user type node_type: type: string const: branch description: type: string nullable: true description: Description of what this node does branches: type: array description: >- Array of branches with conditions to evaluate. Minimum 2 branches required. minItems: 2 maxItems: 10 items: type: object properties: name: type: string description: Name of the branch for identification. description: type: string description: Description of what this branch does. is_default: type: boolean description: >- Whether this is the default branch. Default branch is executed if no other branch conditions are met. conditions: type: array description: Array of conditions to evaluate for this branch. items: type: object properties: type: type: string const: expression_v1 description: >- Type of condition to evaluate. Only expression_v1 is supported for regular branch nodes. expression_v1: type: object description: Boolean expression evaluation structure. properties: op: type: string enum: - AND - OR description: Logical operator for combining conditions. args: type: array description: >- Array of individual condition expressions or nested logical expressions. items: type: object properties: variable_ns: type: string description: >- Namespace for the variable on left-hand side of expression. Allowed values: "" (Default namespace - payload data), "$brand" (tenant/brand properties), "$actor" (user properties of the actor), "$recipient" (user properties of the recipient), "$future_event" (Future event properties), "$workflow" (Workflow properties). required: false enum: - '' - $brand - $actor - $recipient - $future_event - $workflow variable: type: string description: Variable name on left-hand side of expression. op: type: string enum: - '==' - '!=' - '>' - '>=' - < - <= - EMPTY - NON_EMPTY - CONTAINS - NOT_CONTAINS - DATETIME_EQUALS - DATETIME_LT - DATETIME_GT description: Comparison operator for the expression. value: type: string description: Right-hand side operand. args: type: array description: >- Array of conditions for nested logical expressions. nodes: type: array description: Array of nodes to execute when this branch condition is met. TransformNode: type: object description: >- [**Data Transform**](https://docs.suprsend.com/docs/data-transform): Transforms data or generates/overrides variables using scripting languages like JSONNET or Handlebars. required: - node_type - name - variables properties: name: type: string description: Human-readable name of the node example: Transform data node_type: type: string const: transform description: type: string nullable: true description: Description of what this node does variables: type: array description: >- Array of variables to generate or override. Each variable must have a unique key. minItems: 1 items: type: object properties: key: type: string description: Literal string key for the variable. minLength: 1 value_lang: type: string enum: - jsonnet - handlebars description: >- Scripting language to use for deriving the variable value at runtime. value: type: string description: >- Script in the selected language to derive the value of the variable at runtime. minLength: 1 TimeWindowNode: type: object description: >- [**Time Window**](https://docs.suprsend.com/docs/time-window): Restricts workflow execution to specific time windows based on recurrence rules. required: - node_type - name - windows properties: name: type: string description: Human-readable name of the node example: Business hours only node_type: type: string const: timewindow description: type: string nullable: true description: Description of what this node does windows: type: array description: Array of time windows defined using recurrence rule structure. minItems: 1 items: type: object properties: frequency: type: string enum: - daily - weekly_mo2fr - weekly - monthly description: Frequency of the time window recurrence. weekdays: type: array items: type: string enum: - su - mo - tu - we - th - fr - sa description: Which days to include when frequency is 'weekly'. monthdays: type: array description: Which days to include when frequency is 'monthly'. items: type: object properties: pos: type: integer minimum: -31 maximum: 31 description: Day number (-31 to 31). day: type: string enum: - null - su - mo - tu - we - th - fr - sa description: >- Weekday when specifying nth weekday of month. Negative values indicate the nth last occurrence of the weekday in the month. stime: type: string description: Clock start time of the window in HH:MM format (24-hour). example: '08:00' etime: type: string description: Clock end time of the window in HH:MM format (24-hour). example: '17:00' tz_selection: type: string enum: - fixed - recipient description: >- Where to pick timezone from for calculating datetime from recurrence rule. **fixed**: Use a fixed timezone. **recipient**: Use the timezone set in recipient properties. tz_fixed: type: string description: Fixed IANA timezone for calculating datetime in recurrence rule. example: America/New_York SubscriberListOperationAddUserNode: type: object description: >- [**Add User to List**](https://docs.suprsend.com/docs/add-user-to-list): Adds users (actor or recipient) to a subscriber list. Can create the list if it doesn't exist. required: - node_type - name - list_id - user_selection properties: name: type: string description: Human-readable name of the node example: Add to newsletter list node_type: type: string const: subscriberlistoperation_adduser description: type: string nullable: true description: Description of what this node does is_list_id_dynamic: type: boolean default: false description: >- Whether list_id is a static literal string or a handlebars expression. list_id: type: string description: >- List identifier. Can be a static literal string or a handlebars expression added as {{list_id}}. minLength: 1 create_list_if_missing: type: boolean default: false description: Whether to create the list if it doesn't exist. list_name: type: string description: >- Name for the list when creating it. Pass when `create_list_if_missing` is true. minLength: 1 user_selection: type: array description: >- Which users to add to the list. Can select actor, recipient, or both. minItems: 1 items: type: string enum: - actor - recipient SubscriberListOperationRemoveUserNode: type: object description: >- [**Remove User from List**](https://docs.suprsend.com/docs/remove-user-from-list): Removes users (actor or recipient) from the list. List must exist for the operation to succeed. required: - node_type - name - list_id - user_selection properties: name: type: string description: Human-readable name of the node example: Remove from newsletter list node_type: type: string const: subscriberlistoperation_removeuser description: type: string nullable: true description: Description of what this node does is_list_id_dynamic: type: boolean default: false description: >- Whether list_id is a static literal string or a handlebars expression. list_id: type: string description: >- List identifier. Can be a static literal string or a handlebars expression (to compute the list id at runtime. Eg. {{list_id}}). minLength: 1 user_selection: type: array description: >- Which users to remove from the list. Can select actor, recipient, or both. minItems: 1 items: type: string enum: - actor - recipient ObjectOperationAddSubscriptionNode: type: object description: >- [**Subscribe to Object**](https://docs.suprsend.com/docs/subscribe-to-object): Adds users (actor or recipient) as subscribers to an object. Can create the object if it doesn't exist. required: - node_type - name - object_type - object_id - user_selection properties: name: type: string description: Human-readable name of the node example: Add use to team object node_type: type: string const: objectoperation_addsubscription description: type: string nullable: true description: Description of what this node does is_object_id_dynamic: type: boolean default: false description: >- Whether object_type and object_id are static literal strings or handlebars expressions. object_type: type: string description: Type/collection name of the object. minLength: 1 object_id: type: string description: Unique identifier of the object within the object_type. minLength: 1 create_object_if_missing: type: boolean description: Whether to create the object if it doesn't exist. user_selection: type: array description: >- Which users to add as subscribers to the object. Can select actor, recipient, or both. minItems: 1 items: type: string enum: - actor - recipient subscription_properties: type: string description: >- Additional subscription properties which defines the relationship between object and user. Eg. role, designation, etc. Pass as JSONNET expression. example: '{"role": "admin"}' ObjectOperationRemoveSubscriptionNode: type: object description: >- [**Unsubscribe from Object**](https://docs.suprsend.com/docs/unsubscribe-from-object): Removes users (actor or recipient) as subscribers from an object. Object must exist for the operation to succeed. required: - node_type - name - object_type - object_id - user_selection properties: name: type: string description: Human-readable name of the node example: Unsubscribe from project node_type: type: string const: objectoperation_removesubscription description: type: string nullable: true description: Description of what this node does is_object_id_dynamic: type: boolean default: false description: >- Whether object_type and object_id are static literal strings or handlebars expressions. object_type: type: string description: Type/collection name of the object. minLength: 1 object_id: type: string description: Unique identifier of the object within the object_type. minLength: 1 user_selection: type: array description: >- Which users to remove as subscribers from the object. Can select actor, recipient, or both. minItems: 1 items: type: string enum: - actor - recipient UserUpdateNode: type: object description: >- [**Update User Profile**](https://docs.suprsend.com/docs/update-user-profile): Updates user profile properties for either the actor or recipient using JSONNET expression. required: - node_type - name - user_selection - properties properties: name: type: string description: Human-readable name of the node example: Update user profile node_type: type: string const: userupdate description: type: string nullable: true description: Description of what this node does user_selection: type: string enum: - actor - recipient description: >- Select which user to update - actor who triggered the workflow or the recipient of the workflow. properties: type: string description: >- JSONNET script that evaluates at runtime to a map/dictionary of user properties to update. minLength: 1 example: '{"name": "John Doe", "email": "john.doe@example.com"}' InvokeWorkflowNode: type: object description: >- [**Invoke Workflow**](https://docs.suprsend.com/docs/invoke-workflow): Triggers another workflow using data from the current workflow run. Generally used when you have to notify different recipients at different stages of the workflow. required: - node_type - name - workflow - recipient_selection properties: name: type: string description: Human-readable name of the node example: Escalate to the manager node_type: type: string const: invokeworkflow description: type: string nullable: true description: Description of what this node does workflow: type: string description: Slug of the workflow to invoke. minLength: 1 maxLength: 255 pattern: ^[a-z0-9-_]+$ actor_selection: type: string enum: - null - recipient - actor - expression description: >- Where to pick the actor from for the invoke-workflow payload. **recipient**: Use the recipient of the current workflow run. **actor**: Use the actor who triggered the current workflow run. **expression**: Use a JSONNET expression to derive the actor at runtime using data from the current workflow run. actor_expression: type: string description: >- JSONNET expression to derive the actor at runtime for the invoked workflow. Pass when `actor_selection` is 'expression'. Eg. `data["$recipient"].id` minLength: 1 recipient_selection: type: string enum: - recipient - actor - expression description: >- Where to pick the recipient from for the invoke-workflow payload. **recipient**: Use the recipient of the current workflow run. **actor**: Use the actor who triggered the current workflow run. **expression**: Use a JSONNET expression to derive the recipient at runtime using data from the current workflow run. recipient_expression: type: string description: >- JSONNET expression to derive the recipient at runtime for the invoked workflow. Pass when `recipient_selection` is 'expression'. Eg. `data["$recipient"].manager_id` minLength: 1 data: type: string description: >- JSONNET expression to derive the data field for the invoke-workflow payload. append_current_run_data: type: boolean description: >- Whether the current workflow-run data should be passed as payload of the invoked workflow. SendEmailNode: type: object description: >- [**Email**](https://docs.suprsend.com/docs/delivery-single-channel): Sends email notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send welcome email node_type: type: string const: send_email description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendSmsNode: type: object description: >- [**SMS**](https://docs.suprsend.com/docs/delivery-single-channel)): Sends SMS text message notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send OTP SMS node_type: type: string const: send_sms description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for SMS notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendWhatsappNode: type: object description: >- [**WhatsApp**](https://docs.suprsend.com/docs/delivery-single-channel): Sends WhatsApp message notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send WhatsApp order confirmation node_type: type: string const: send_whatsapp description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for WhatsApp notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendMobilePushNode: type: object description: >- [**Mobile Push**](https://docs.suprsend.com/docs/delivery-single-channel): Sends push notifications to mobile devices (Android and iOS) using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send mobile push notification node_type: type: string const: send_mobile_push description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for mobile push notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendInboxNode: type: object description: >- [**Inbox**](https://docs.suprsend.com/docs/delivery-single-channel): Sends in-app inbox notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send in-app notification node_type: type: string const: send_inbox description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for in-app inbox notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendWebpushNode: type: object description: >- [**Web Push**](https://docs.suprsend.com/docs/delivery-single-channel): Sends web push notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send web push notification node_type: type: string const: send_webpush description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for web push notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendSlackNode: type: object description: >- [**Slack**](https://docs.suprsend.com/docs/delivery-single-channel): Sends Slack message notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send Slack notification node_type: type: string const: send_slack description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for Slack notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendMsTeamsNode: type: object description: >- [**Microsoft Teams**](https://docs.suprsend.com/docs/delivery-single-channel): Sends Microsoft Teams chat notifications using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send Teams notification node_type: type: string const: send_ms_teams description: type: string nullable: true description: Description of what this node does template: type: string description: Slug of the template used for Microsoft Teams notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ SendMultiChannelNode: type: object description: >- [**Multi-Channel**](https://docs.suprsend.com/docs/delivery-multi-channel): Sends notifications across multiple channels simultaneously using a specified template. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send multi-channel notification node_type: type: string const: send_multi_channel description: type: string nullable: true description: Description of what this node does template: type: string description: >- Slug of the template used for notification content across all channels. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ channels: type: array description: >- Specific channels to use when sending multi-channel notification. If not provided, all channels will be used. required: true items: type: string enum: - sms - email - androidpush - iospush - webpush - inbox - whatsapp - slack - ms_teams channels_expr: type: string description: jq-expression for preparing channel list dynamically at runtime. minLength: 2 SendSmartChannelRoutingNode: type: object description: >- [**Smart Channel Routing**](https://docs.suprsend.com/docs/smart-delivery): Sends notification subsequently at each consecutive channel with a delay (computed using time-to-live) between each channel. required: - node_type - name - template properties: name: type: string description: Human-readable name of the node example: Send smart channel notification node_type: type: string const: send_smart_channel_routing description: type: string nullable: true description: Description of what this node does template: type: string description: >- Slug of the template used for smart channel routing notification content. minLength: 1 maxLength: 120 pattern: ^[a-z0-9-_]+$ channels: type: array description: Available channels for smart routing algorithm to choose from. items: type: string enum: - sms - email - androidpush - iospush - webpush - inbox - whatsapp - slack - ms_teams channels_expr: type: string description: >- jq-expression for preparing available channel list dynamically at runtime. minLength: 2 success: type: string description: Success metric to track for smart channel routing. examples: delivered: summary: Notification delivered value: delivered seen: summary: Notification seen value: seen interacted: summary: User clicked the notification value: interacted custom_event: summary: Custom event name value: success_is_event: type: boolean description: >- Whether the success metric is a custom event. If not, notification status will be used to determine success. ttl_value: type: string description: >- Time-to-live value for the smart channel routing notification in static duration format. example: 1h mandatory_channels: type: array description: >- Channels that will be sent immediately regardless of smart routing logic. items: type: string enum: - sms - email - androidpush - iospush - webpush - inbox - whatsapp - slack - ms_teams routing_basis: type: string enum: - cost_low_to_high description: >- Basis for smart channel routing. Determines the order in which channels are tried. Right now only `cost_low_to_high` is supported. We'll be adding more routing rules like in the order of engagement in future. ErrorResponse: type: object properties: code: type: integer description: HTTP status code error_code: type: string description: Specific error code identifier type: type: string description: Error type classification message: type: string description: Human-readable error message detail: type: string description: Additional error details Schedule: type: object description: Static schedule configuration for digest notifications. properties: frequency: type: string enum: - minutely - hourly - daily - weekly_mo2fr - weekly - monthly description: Frequency of the digest schedule. interval: type: integer minimum: 1 description: >- Multiplier for recurrence schedule. Eg. 2 for every 2 hours, 3 for every 3 days, etc. weekdays: type: array items: type: string enum: - su - mo - tu - we - th - fr - sa description: Which days to include when frequency is 'weekly'. monthdays: type: array items: type: object properties: pos: type: integer minimum: -31 maximum: 31 day: type: string enum: - null - su - mo - tu - we - th - fr - sa description: Which days to include when frequency is 'monthly'. time: type: string description: Time of day to send digest in HH:MM format (24-hour). examples: - '09:00' - '18:30' dtstart: type: string description: When to start schedule calculation from in ISO datetime format. tz_selection: type: string enum: - fixed - recipient description: |- timezone of the recurring schedule. **fixed**: Fixed timezone. **recipient**: Recipient's timezone picked from user properties. tz_fixed: type: string description: Fixed IANA timezone. pattern: ^[A-Za-z_/]+$ examples: new_york: summary: New York timezone value: America/New_York london: summary: London timezone value: Europe/London responses: AuthenticationError: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 401 error_code: authentication_failed type: AuthenticationFailed message: Invalid service token. detail: Invalid service token. NotFoundError: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 404 error_code: not_found type: NotFound message: workspace 'demo' not found detail: workspace 'demo' not found securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ServiceTokenAuth: type: apiKey in: header name: ServiceToken description: >- You can get Service Token from [SuprSend dashboard -> Account Settings -> Service Tokens](https://app.suprsend.com/en/account-settings/service-tokens) section. ````