Knock Workflows API

openapi: 3.2.0
info:
  title: Knock Audiences Accounts Workflows API
  version: '1.0'
  description: Manage static Audiences and their members. Audiences power lifecycle messaging — when a user joins an audience, configured workflows fire automatically.
  contact:
    name: Knock
    url: https://knock.app
  license:
    name: Proprietary
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: Workflows let you express your cross-channel notification logic.
  name: Workflows
paths:
  /v1/workflows/{workflow_key}/validate:
    put:
      callbacks: {}
      description: 'Validates a workflow payload without persisting it. Some read-only fields will be empty as they are generated by the system when persisted.


        Note: Validating a workflow is only done in the development environment context.

        '
      operationId: validateWorkflow
      parameters:
      - description: The key of the workflow.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the WorkflowRequest request under the workflow key.
              example:
                workflow:
                  name: My Workflow
                  steps:
                  - channel_key: in-app-feed
                    name: Channel 1
                    ref: channel_1
                    template:
                      action_url: '{{ vars.app_url }}'
                      markdown_body: Hello **{{ recipient.name }}**
                    type: channel
              properties:
                workflow:
                  $ref: '#/components/schemas/WorkflowRequest'
              required:
              - workflow
              title: WrappedWorkflowRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Workflow response under the `workflow` key.
                example:
                  workflow:
                    active: false
                    categories:
                    - marketing
                    - black-friday
                    conditions:
                      all:
                      - argument: admin
                        operator: equal_to
                        variable: recipient.role
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: This is a dummy workflow for demo purposes.
                    environment: development
                    key: december-16-demo
                    name: december-16-demo
                    settings:
                      override_preferences: true
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    steps:
                    - channel_key: in-app-feed
                      channel_type: in_app_feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ data.onboarding_url }}'
                        markdown_body: Hello **{{ recipient.name }}**. Click here to get started.
                      type: channel
                    - ref: delay_1
                      settings:
                        delay_for:
                          unit: hours
                          value: 1
                      type: delay
                    - channel_key: postmark
                      channel_type: email
                      ref: email_1
                      template:
                        html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.onboarding_url }}'>Get started here</a>.</p>
                        settings:
                          layout_key: default
                        subject: Welcome to {{ vars.app_name }}!
                      type: channel
                    trigger_data_json_schema:
                      properties:
                        onboarding_url:
                          type: string
                      required:
                      - onboarding_url
                      type: object
                    trigger_frequency: every_trigger
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  workflow:
                    $ref: '#/components/schemas/Workflow'
                required:
                - workflow
                title: WrappedWorkflowResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate a workflow
      tags:
      - Workflows
  /v1/workflows/{workflow_key}/run:
    put:
      callbacks: {}
      description: Runs the latest version of a committed workflow in a given environment using the params provided.
      operationId: runWorkflow
      parameters:
      - description: The key of the workflow.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunWorkflowRequest'
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunWorkflowResponse'
          description: OK
      summary: Run a workflow
      tags:
      - Workflows
  /v1/workflows/{workflow_key}/steps/{step_ref}/preview_template:
    post:
      callbacks: {}
      description: Generates a rendered template for a given channel step in a workflow.
      operationId: previewWorkflowTemplate
      parameters:
      - description: The key of the workflow.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The reference key of the channel step in the workflow to preview.
        in: path
        name: step_ref
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewWorkflowTemplateRequest'
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewWorkflowTemplateResponse'
          description: OK
      summary: Preview a workflow template
      tags:
      - Workflows
  /v1/workflows:
    get:
      callbacks: {}
      description: Returns a paginated list of workflows available in a given environment. The workflows are returned alphabetically by `key`.
      operationId: listWorkflows
      parameters:
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries after.
        in: query
        name: after
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries before.
        in: query
        name: before
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The number of entries to fetch per-page.
        in: query
        name: limit
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A paginated list of Workflow. Contains a list of entries and page information.
                example:
                  entries:
                  - active: false
                    categories:
                    - marketing
                    - black-friday
                    conditions:
                      all:
                      - argument: admin
                        operator: equal_to
                        variable: recipient.role
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: This is a dummy workflow for demo purposes.
                    environment: development
                    key: december-16-demo
                    name: december-16-demo
                    settings:
                      override_preferences: true
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    steps:
                    - channel_key: in-app-feed
                      channel_type: in_app_feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ data.onboarding_url }}'
                        markdown_body: Hello **{{ recipient.name }}**. Click here to get started.
                      type: channel
                    - ref: delay_1
                      settings:
                        delay_for:
                          unit: hours
                          value: 1
                      type: delay
                    - channel_key: postmark
                      channel_type: email
                      ref: email_1
                      template:
                        html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.onboarding_url }}'>Get started here</a>.</p>
                        settings:
                          layout_key: default
                        subject: Welcome to {{ vars.app_name }}!
                      type: channel
                    trigger_data_json_schema:
                      properties:
                        onboarding_url:
                          type: string
                      required:
                      - onboarding_url
                      type: object
                    trigger_frequency: every_trigger
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Workflow'
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedWorkflowResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List workflows
      tags:
      - Workflows
  /v1/workflows/{workflow_key}/activate:
    put:
      callbacks: {}
      description: 'Activates (or deactivates) a workflow in a given environment. Read more in the [docs](https://docs.knock.app/concepts/workflows#workflow-status).


        Note: This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.

        '
      operationId: activateWorkflow
      parameters:
      - description: The key of the workflow.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              example:
                status: true
              properties:
                status:
                  description: Whether to activate or deactivate the workflow. Set to `true` by default, which will activate the workflow.
                  example: true
                  type: boolean
                  x-struct: null
                  x-validate: null
              required:
              - status
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Workflow response under the `workflow` key.
                example:
                  workflow:
                    active: false
                    categories:
                    - marketing
                    - black-friday
                    conditions:
                      all:
                      - argument: admin
                        operator: equal_to
                        variable: recipient.role
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: This is a dummy workflow for demo purposes.
                    environment: development
                    key: december-16-demo
                    name: december-16-demo
                    settings:
                      override_preferences: true
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    steps:
                    - channel_key: in-app-feed
                      channel_type: in_app_feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ data.onboarding_url }}'
                        markdown_body: Hello **{{ recipient.name }}**. Click here to get started.
                      type: channel
                    - ref: delay_1
                      settings:
                        delay_for:
                          unit: hours
                          value: 1
                      type: delay
                    - channel_key: postmark
                      channel_type: email
                      ref: email_1
                      template:
                        html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.onboarding_url }}'>Get started here</a>.</p>
                        settings:
                          layout_key: default
                        subject: Welcome to {{ vars.app_name }}!
                      type: channel
                    trigger_data_json_schema:
                      properties:
                        onboarding_url:
                          type: string
                      required:
                      - onboarding_url
                      type: object
                    trigger_frequency: every_trigger
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  workflow:
                    $ref: '#/components/schemas/Workflow'
                required:
                - workflow
                title: WrappedWorkflowResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Activate a workflow
      tags:
      - Workflows
  /v1/workflows/{workflow_key}:
    get:
      callbacks: {}
      description: Retrieve a workflow by its key in a given environment.
      operationId: getWorkflow
      parameters:
      - description: The key of the workflow to retrieve.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowWorkflowResponse'
          description: OK
      summary: Get a workflow
      tags:
      - Workflows
    put:
      callbacks: {}
      description: 'Updates a workflow of a given key, or creates a new one if it does not yet exist.


        Note: this endpoint only operates on workflows in the `development` environment.

        '
      operationId: upsertWorkflow
      parameters:
      - description: The key of the workflow.
        in: path
        name: workflow_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks.
        in: query
        name: force
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to commit the resource at the same time as modifying it.
        in: query
        name: commit
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The message to commit the resource with, only used if `commit` is `true`.
        in: query
        name: commit_message
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the WorkflowRequest request under the workflow key.
              example:
                workflow:
                  name: My Workflow
                  steps:
                  - channel_key: in-app-feed
                    name: Channel 1
                    ref: channel_1
                    template:
                      action_url: '{{ vars.app_url }}'
                      markdown_body: Hello **{{ recipient.name }}**
                    type: channel
              properties:
                workflow:
                  $ref: '#/components/schemas/WorkflowRequest'
              required:
              - workflow
              title: WrappedWorkflowRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Workflow response under the `workflow` key.
                example:
                  workflow:
                    active: false
                    categories:
                    - marketing
                    - black-friday
                    conditions:
                      all:
                      - argument: admin
                        operator: equal_to
                        variable: recipient.role
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: This is a dummy workflow for demo purposes.
                    environment: development
                    key: december-16-demo
                    name: december-16-demo
                    settings:
                      override_preferences: true
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    steps:
                    - channel_key: in-app-feed
                      channel_type: in_app_feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ data.onboarding_url }}'
                        markdown_body: Hello **{{ recipient.name }}**. Click here to get started.
                      type: channel
                    - ref: delay_1
                      settings:
                        delay_for:
                          unit: hours
                          value: 1
                      type: delay
                    - channel_key: postmark
                      channel_type: email
                      ref: email_1
                      template:
                        html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.onboarding_url }}'>Get started here</a>.</p>
                        settings:
                          layout_key: default
                        subject: Welcome to {{ vars.app_name }}!
                      type: channel
                    trigger_data_json_schema:
                      properties:
                        onboarding_url:
                          type: string
                      required:
                      - onboarding_url
                      type: object
                    trigger_frequency: every_trigger
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  workflow:
                    $ref: '#/components/schemas/Workflow'
                required:
                - workflow
                title: WrappedWorkflowResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert a workflow
      tags:
      - Workflows
  /v1/workflows/{key}/trigger:
    post:
      callbacks: {}
      description: Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.
      operationId: triggerWorkflow (2)
      parameters:
      - description: Key of the workflow to trigger.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              actor: mr_dna
              cancellation_key: isla_nublar_incident_1993
              data:
                affected_areas:
                - visitor_center
                - raptor_pen
                - trex_paddock
                attraction_id: paddock_rex_01
                evacuation_protocol: active
                message: Life finds a way
                severity: critical
                system_status: fences_failing
              recipients:
              - dr_grant
              - dr_sattler
              - dr_malcolm
              tenant: ingen_isla_nublar
            schema:
              $ref: '#/components/schemas/TriggerWorkflowRequest'
        description: Params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerWorkflowResponse'
          description: OK
      summary: Trigger workflow
      tags:
      - Workflows
      x-idempotent: true
      x-ratelimit-tier: 5
  /v1/workflows/{key}/cancel:
    post:
      callbacks: {}
      description: When invoked for a workflow using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally be provided one or more recipients to scope the request to.
      operationId: cancelWorkflow
      parameters:
      - description: The key of the workflow to cancel.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              cancellation_key: cancel-workflow-123
              recipients:
              - jhammond
            schema:
              $ref: '#/components/schemas/CancelWorkflowRequest'
        description: Params
        required: true
      responses:
        '204':
          description: No Content
      summary: Cancel workflow
      tags:
      - Workflows
      x-ratelimit-tier: 5
components:
  schemas:
    WorkflowWebhookStep:
      description: A webhook step within a workflow to send an HTTP request to a generic channel. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
      example:
        channel_group_key: null
        channel_key: pagerduty
        channel_type: http
        conditions: null
        description: This is a description of the channel step
        name: Webhook channel step
        ref: channel_step
        send_windows: null
        template:
          body: null
          headers:
          - key: X-API-Key
            value: '1234567890'
          method: get
          query_params:
          - key: key
            value: value
          url: https://example.com
        type: channel
      properties:
        channel_group_key:
          description: The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.
          example: email
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        channel_key:
          description: The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.
          example: postmark
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        channel_type:
          description: The type of the channel step. Always `http` for webhook steps.
          enum:
          - http
          example: http
          type: string
          x-struct: null
          x-validate: null
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - x-struct: null
            x-validate: null
          description: A set of conditions to be evaluated for this channel step.
          type: object
          x-struct: null
          x-validate: null
        description:
          description: An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.
          example: Send a message to the channel
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Channel
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ref:
          description: The reference key of the workflow step. Must be unique per workflow.
          example: channel_step
          type: string
          x-struct: null
          x-validate: null
        send_windows:
          description: A list of send window objects. Must include one send window object per day of the week.
          items:
            $ref: '#/components/schemas/SendWindow'
          type:
          - array
          - 'null'
          x-stru

# --- truncated at 32 KB (212 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock-app/refs/heads/main/openapi/knock-app-workflows-api-openapi.yml