SuprSend Workflow API
The Workflow API from SuprSend — 4 operation(s) for workflow.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast Workflow API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Workflow
paths:
/v1/{workspace}/workflow/:
get:
summary: List Workflows
description: Retrieve a list of workflows in a workspace.
operationId: list-workflows
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
label: List Workflows
source: "curl -X GET \"https://management-api.suprsend.com/v1/{workspace}/workflow/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json'\n"
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Workspace slug (staging, production, etc.)
- in: query
name: mode
schema:
type: string
enum:
- draft
- live
default: draft
description: Mode to filter workflows (draft or live). By default, draft workflows are returned.
- in: query
name: slugs
schema:
type: string
description: Comma-separated list of workflow slugs to filter. This can be used to filter workflows by slug.
responses:
'200':
description: Successfully retrieved list of workflows
content:
application/json:
schema:
type: object
properties:
meta:
type: object
properties:
count:
type: integer
description: Total number of workflows matching the query
example: 92
limit:
type: integer
description: Number of results returned per page
example: 10
offset:
type: integer
description: Offset value passed in the request
example: 0
description: Metadata related to pagination information
results:
type: array
items:
$ref: '#/components/schemas/Workflow'
description: Array of workflows along with their node tree.
example:
meta:
count: 92
limit: 10
offset: 0
results:
- $schema: https://schema.suprsend.com/workflow/v1/schema.json
slug: survey-reminder
is_enabled: true
created_at: '2025-06-27T03:26:48.793551Z'
last_executed_at: '2025-06-27T04:48:20.653366Z'
name: Survey Reminder
description: null
updated_at: '2025-06-27T03:36:05.623939Z'
commit_message: Survey completed
hash: ed3e630c1526170564c962db00dbfcfef997e995f62f67c068a8c9c1d5efbc13
status: active
category: transactional
tags:
- reminder
ratelimit: null
conditions: []
trigger_type: api
trigger_events: []
override_recipients_type: null
override_recipients_user_expr: null
override_recipients_single_object_fields_expr: null
override_actor_user_expr: null
override_tenant_expr: null
active_at: '2025-06-27T03:36:05.623845Z'
updated_by:
name: Jane Doe
email: user@example.com
tree:
nodes:
- name: Multi-Channel
node_type: send_multi_channel
properties:
template: 11-performance-review-session
channels: []
channels_expr: null
success: seen
success_is_event: false
description: ''
schema_version: '1'
validation_result:
is_valid: true
'404':
$ref: '#/components/responses/NotFoundError'
description: Workflow not found
'401':
$ref: '#/components/responses/AuthenticationError'
description: AuthenticationFailed
tags:
- Workflow
/v1/{workspace}/workflow/{slug}/:
get:
summary: Get Workflow Details
description: Fetch workflow corresponding to the given slug in a workspace.
operationId: get-workflow
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
label: Get Workflow
source: "curl -X GET \"https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json'\n"
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Workspace slug (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.
- in: query
name: mode
schema:
type: string
enum:
- draft
- live
default: draft
description: Which workflow version to fetch (draft or live). By default, draft version is returned.
responses:
'200':
description: Successfully retrieved workflow
content:
application/json:
schema:
$ref: '#/components/schemas/Workflow'
example:
$schema: https://schema.suprsend.com/workflow/v1/schema.json
slug: survey-reminder
is_enabled: true
created_at: '2025-06-27T03:26:48.793551Z'
last_executed_at: '2025-06-27T04:48:20.653366Z'
name: Survey Reminder
description: null
updated_at: '2025-06-27T03:36:05.623939Z'
commit_message: Survey completed
hash: ed3e630c1526170564c962db00dbfcfef997e995f62f67c068a8c9c1d5efbc13
status: active
category: transactional
tags:
- reminder
ratelimit: null
conditions: []
trigger_type: api
trigger_events: []
override_recipients_type: null
override_recipients_user_expr: null
override_recipients_single_object_fields_expr: null
override_actor_user_expr: null
override_tenant_expr: null
active_at: '2025-06-27T03:36:05.623845Z'
updated_by:
name: Jane Doe
email: user@example.com
tree:
nodes:
- name: Multi-Channel
node_type: send_multi_channel
properties:
template: 11-performance-review-session
channels: []
channels_expr: null
success: seen
success_is_event: false
description: ''
schema_version: '1'
validation_result:
is_valid: true
'404':
$ref: '#/components/responses/NotFoundError'
description: Workflow not found
'401':
$ref: '#/components/responses/AuthenticationError'
description: AuthenticationFailed - Invalid service token.
tags:
- Workflow
post:
summary: Create or Update Workflow
description: Create a new workflow or update the draft version of an existing one
operationId: upsert-workflow
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
source: "curl -X POST \"https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Welcome Email\",\n \"description\": \"Sends welcome email to new users\",\n \"category\": \"transactional\",\n \"tags\": [\"welcome\", \"onboarding\"],\n \"tree\": {\n \"nodes\": [\n {\n \"name\": \"Send Email\",\n \"node_type\": \"send_email\",\n \"properties\": {\n \"template\": \"welcome-email-template\",\n \"subject\": \"Welcome to our platform!\"\n },\n \"description\": \"Send welcome email to new users\"\n }\n ]\n }\n }'\n"
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
'404':
$ref: '#/components/responses/NotFoundError'
'401':
$ref: '#/components/responses/AuthenticationError'
tags:
- Workflow
delete:
summary: Delete Workflow
description: Permanently deletes a workflow by providing it's slug.
operationId: delete-workflow
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
label: Delete Workflow
source: "curl -X DELETE \"https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json'\n"
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Which workspace workflow belongs to (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.
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/NotFoundError'
description: Workflow not found
'401':
$ref: '#/components/responses/AuthenticationError'
description: AuthenticationFailed - Invalid service token.
tags:
- Workflow
/v1/{workspace}/workflow/{slug}/commit/:
patch:
summary: Commit Workflow
description: Commit a workflow to make the draft version live.
operationId: commit-workflow
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
source: "curl -X PATCH \"https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/commit/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json'\n"
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Workspace to which the workflow belongs (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.
- in: query
name: commit_message
required: false
schema:
type: string
description: Commit message describing the changes
responses:
'202':
description: Workflow committed successfully. The response will be the latest draft version after the commit.
content:
application/json:
schema:
$ref: '#/components/schemas/Workflow'
'404':
$ref: '#/components/responses/NotFoundError'
description: Workflow not found
'401':
$ref: '#/components/responses/AuthenticationError'
description: AuthenticationFailed - Invalid service token.
tags:
- Workflow
/v1/{workspace}/workflow/{slug}/enable/:
patch:
summary: Enable/Disable Workflow
description: Enable or disable a workflow. Disabled workflows will not be executed when triggered. By default, workflows are enabled unless you explicitly disable them.
operationId: toggle-workflow
servers:
- url: https://management-api.suprsend.com
security:
- ServiceTokenAuth: []
x-codeSamples:
- lang: cURL
label: Toggle Workflow
source: "curl -X PATCH \"https://management-api.suprsend.com/v1/{workspace}/workflow/{slug}/enable/\" \\\n --header 'Authorization: ServiceToken <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"is_enabled\": true\n }'\n"
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Workspace to which the workflow belongs (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.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- is_enabled
properties:
is_enabled:
type: boolean
description: Set to true to enable the workflow, false to disable it.
example:
is_enabled: true
responses:
'202':
description: Workflow status updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Workflow'
'404':
$ref: '#/components/responses/NotFoundError'
description: Workflow not found
'401':
$ref: '#/components/responses/AuthenticationError'
description: AuthenticationFailed - Invalid service token.
tags:
- Workflow
components:
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
schemas:
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
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-_]+$
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. \n\n**recipient**: Use the recipient of the current workflow run. \n\n**actor**: Use the actor who triggered the current workflow run. \n\n**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. \n\n**recipient**: Use the recipient of the current workflow run. \n\n**actor**: Use the actor who triggered the current workflow run. \n\n**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.
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. \n\n**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. \n\n**fixed**: Static window duration added as XXdXXhXXmXXs. Eg. 30s, 1h, 1d. \n\n**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`. \n\n**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. \n\n**Fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. \n\n**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
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. \n\n**fixed**: Fixed timezone. \n\n**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
Workflow:
type: object
properties:
$schema:
type: string
format: uri
description: Schema URL for workflow validation
example: https://schema.suprsend.com/workflow/v1/schema.json
slug:
type: string
description: Unique identifier for the workflow
minLength: 1
maxLength: 255
pattern: ^[a-z0-9-_]+$
example: welcome-sequence
is_enabled:
type: boolean
description: Whether the workflow is enabled
example: true
created_at:
type: string
format: date-time
description: When the workflow was created
last_executed_at:
type: string
format: date-time
description: When the workflow was last executed
nullable: true
name:
type: string
description: Human-readable name of the workflow
example: Welcome Sequence
description:
type: string
nullable: true
description: Description explaining the usecase of the workflow
updated_at:
type: string
format: date-time
description: When the workflow was last updated
commit_m
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-workflow-api-openapi.yml