SuprSend Workflow API

openapi: 3.2.0
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:
  schemas:
    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-_]+$
    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
    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. \n\n**static**: Schedule is fixed and will be used for all recipients. \n\n**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.
    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
    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-_]+$
    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.
    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
    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 ope

# --- 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