Knock Workflows API

openapi: 3.0.3
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'
                    nullable: false
                    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:
    PushChannelDataTokensOnly:
      description: Push channel data.
      example:
        tokens:
        - push_token_1
        - push_token_2
      properties:
        tokens:
          description: A list of push channel tokens.
          items:
            description: The device token to send the push notification to.
            nullable: false
            type: string
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
      required:
      - tokens
      title: PushChannelDataTokensOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PushChannelDataTokensOnly
      x-validate: null
    TriggerWorkflowResponse:
      description: The response from triggering a workflow.
      example:
        workflow_run_id: 123e4567-e89b-12d3-a456-426614174000
      properties:
        workflow_run_id:
          description: This value allows you to track individual messages associated with this trigger request.
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
          x-struct: null
          x-validate: null
      required:
      - workflow_run_id
      title: TriggerWorkflowResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.TriggerWorkflowResponse
      x-validate: null
    RecipientReference_2:
      description: A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
      example: user_123
      oneOf:
      - description: The ID of the user which is used as the reference for the recipient.
        example: user_123
        nullable: false
        title: UserReference
        type: string
        x-struct: null
        x-validate: null
      - description: A reference to a recipient object.
        example:
          collection: projects
          id: project_123
        properties:
          collection:
            description: The collection the recipient object belongs to.
            example: projects
            nullable: false
            type: string
            x-struct: null
            x-validate: null
          id:
            description: An identifier for the recipient object.
            example: project_123
            nullable: false
            type: string
            x-struct: null
            x-validate: null
        title: ObjectReference
        type: object
        x-struct: null
        x-validate: null
      title: RecipientReference
      x-struct: Elixir.SwitchboardWeb.V1.Specs.RecipientReference
      x-validate: null
    WebhookTemplate:
      description: A webhook template. By default, a webhook step will use the request settings you configured in your webhook channel. You can override this as you see fit on a per-step basis.
      example:
        body: null
        headers:
        - key: X-API-Key
          value: '1234567890'
        method: get
        query_params:
        - key: ke

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