Knock Management API (mAPI)

components:
  responses: {}
  schemas:
    PreviewTemplateResponse:
      description: A response to a template preview request.
      example:
        content_type: email
        result: success
        template:
          html_body: <p>Welcome to Acme!</p>
          subject: Hello John
          text_body: Welcome to Acme!
      properties:
        content_type:
          description: The content type of the preview.
          enum:
          - email
          - in_app_feed
          - push
          - chat
          - sms
          type: string
          x-struct: null
          x-validate: null
        errors:
          description: A list of errors encountered during rendering. Present when result is "error".
          items:
            description: A rendering error with optional location information.
            example:
              field: html_content
              line: 1
              message: 'Reason: expected end of string, line: 1'
            properties:
              field:
                description: The template field that caused the error, if available.
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              line:
                description: The line number where the error occurred, if available.
                nullable: true
                type: integer
                x-struct: null
                x-validate: null
              message:
                description: A human-readable description of the error.
                type: string
                x-struct: null
                x-validate: null
            required:
            - message
            type: object
            x-struct: null
            x-validate: null
          nullable: true
          type: array
          x-struct: null
          x-validate: null
        result:
          description: The result of the preview.
          enum:
          - success
          - error
          type: string
          x-struct: null
          x-validate: null
        template:
          anyOf:
          - $ref: '#/components/schemas/EmailTemplate'
          - $ref: '#/components/schemas/InAppFeedTemplate'
          - $ref: '#/components/schemas/PushTemplate'
          - $ref: '#/components/schemas/ChatTemplate'
          - $ref: '#/components/schemas/SmsTemplate'
          description: The rendered template, ready to be previewed.
          type: object
          x-struct: null
          x-validate: null
      required:
      - result
      - content_type
      title: PreviewTemplateResponse
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PreviewTemplateResponse
      x-validate: null
    RequestTemplateQueryParamsArray:
      description: A list of key-value pairs for the request query params. Each object should contain key and value fields
        with string values.
      example:
      - key: key
        value: value
      items:
        properties:
          key:
            description: The key of the query param.
            example: key
            type: string
            x-struct: null
            x-validate: null
          value:
            description: The value of the query param.
            example: value
            type: string
            x-struct: null
            x-validate: null
        required:
        - key
        - value
        type: object
        x-struct: null
        x-validate: null
      title: RequestTemplateQueryParamsArray
      type: array
      x-struct: null
      x-validate: null
    SmsChannelSettings:
      description: SMS channel settings. Only used as configuration as part of a workflow channel step.
      example:
        link_tracking: true
      properties:
        link_tracking:
          description: Whether to track link clicks on SMS notifications.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
      title: SmsChannelSettings
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.SmsChannelSettings
      x-validate: null
    WrappedEmailLayoutRequestRequest:
      description: Wraps the EmailLayoutRequest request under the email_layout key.
      example:
        email_layout:
          footer_links:
          - text: Example
            url: http://example.com
          html_layout: <html><body>Hello, world!</body></html>
          name: Transactional
          text_layout: Hello, world!
      properties:
        email_layout:
          $ref: '#/components/schemas/EmailLayoutRequest'
      required:
      - email_layout
      title: WrappedEmailLayoutRequestRequest
      type: object
      x-struct: null
      x-validate: null
    WorkflowStep:
      anyOf:
      - $ref: '#/components/schemas/WorkflowWebhookStep'
      - $ref: '#/components/schemas/WorkflowInAppFeedStep'
      - $ref: '#/components/schemas/WorkflowChatStep'
      - $ref: '#/components/schemas/WorkflowSmsStep'
      - $ref: '#/components/schemas/WorkflowPushStep'
      - $ref: '#/components/schemas/WorkflowEmailStep'
      - $ref: '#/components/schemas/WorkflowAIAgentStep'
      - $ref: '#/components/schemas/WorkflowDelayStep'
      - $ref: '#/components/schemas/WorkflowBatchStep'
      - $ref: '#/components/schemas/WorkflowFetchStep'
      - $ref: '#/components/schemas/WorkflowUpdateDataStep'
      - $ref: '#/components/schemas/WorkflowUpdateObjectStep'
      - $ref: '#/components/schemas/WorkflowUpdateTenantStep'
      - $ref: '#/components/schemas/WorkflowUpdateUserStep'
      - $ref: '#/components/schemas/WorkflowThrottleStep'
      - $ref: '#/components/schemas/WorkflowBranchStep'
      - $ref: '#/components/schemas/WorkflowRandomCohortStep'
      - $ref: '#/components/schemas/WorkflowTriggerWorkflowStep'
      description: A step within a workflow. Each workflow step, regardless of its type, share a common set of core attributes
        (`type`, `ref`, `name`, `description`, `conditions`).
      example:
        channel_group_key: null
        channel_key: postmark
        channel_overrides: null
        channel_type: email
        conditions: null
        description: This is a description of the channel step
        name: Email channel step
        ref: channel_step
        send_windows: null
        template:
          html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.sign_in_url }}'>Get started
            here</a>.</p>
          settings:
            layout_key: default
          subject: Welcome to {{ vars.app_name }}
          text_body: 'Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} Get started here: {{ data.sign_in_url }}.'
        type: channel
      title: WorkflowStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowStep
      x-validate: null
    RequestTemplateQueryParamsString:
      description: A template string that should resolve to a JSON object representing the query params.
      example: '{{ data.request_query_params }}'
      title: RequestTemplateQueryParamsString
      type: string
      x-struct: null
      x-validate: null
    EmailImageBlock:
      description: An image block in an email template.
      example:
        alt: Example image
        layout_attrs:
          horizontal_align: center
          padding_bottom: 4
          padding_left: 0
          padding_right: 0
          padding_top: 4
        style_attrs:
          width: 25%
        type: image
        url: https://example.com/image.jpg
      properties:
        action:
          description: Optional action URL for the image.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        alt:
          description: Alt text for the image.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        id:
          description: The ID of the block.
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
          x-struct: null
          x-validate: null
        layout_attrs:
          description: The layout attributes of the block.
          properties:
            horizontal_align:
              description: The horizontal alignment of the block.
              enum:
              - left
              - center
              - right
              type: string
              x-struct: null
              x-validate: null
            padding_bottom:
              description: The padding_bottom layout attribute of the block.
              type: integer
              x-struct: null
              x-validate: null
            padding_left:
              description: The padding_left layout attribute of the block.
              type: integer
              x-struct: null
              x-validate: null
            padding_right:
              description: The padding_right layout attribute of the block.
              type: integer
              x-struct: null
              x-validate: null
            padding_top:
              description: The padding_top layout attribute of the block.
              type: integer
              x-struct: null
              x-validate: null
          required:
          - padding_top
          - padding_right
          - padding_bottom
          - padding_left
          - horizontal_align
          type: object
          x-struct: null
          x-validate: null
        style_attrs:
          description: The style attributes of the image.
          properties:
            width:
              description: The width of the image.
              example: 100%
              type: string
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the block.
          enum:
          - image
          example: image
          type: string
          x-struct: null
          x-validate: null
        url:
          description: The URL of the image to display.
          format: uri
          type: string
          x-struct: null
          x-validate: null
        version:
          description: The version of the block schema. This is automatically managed by Knock and should not be set manually.
            Currently all blocks are at version 1.
          example: 1
          type: integer
          x-struct: null
          x-validate: null
      required:
      - type
      - url
      title: EmailImageBlock
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.EmailBlocks.ImageBlock
      x-validate: null
    PaginatedVariableResponse:
      description: A paginated list of Variable. Contains a list of entries and page information.
      example:
        entries:
        - description: This is a description of my variable.
          environment_values:
            development: dev_value
            production: prod_value
          inserted_at: '2021-01-01T00:00:00Z'
          key: my_variable
          type: public
          updated_at: '2021-01-01T00:00:00Z'
          value: my_value
        page_info:
          after: null
          before: null
          page_size: 25
      properties:
        entries:
          description: A list of entries.
          items:
            $ref: '#/components/schemas/Variable'
          nullable: false
          type: array
          x-struct: null
          x-validate: null
        page_info:
          $ref: '#/components/schemas/PageInfo'
      required:
      - entries
      - page_info
      title: PaginatedVariableResponse
      type: object
      x-struct: null
      x-validate: null
    ChannelGroupRuleRequest:
      description: A rule that determines if a channel should be executed as part of a channel group.
      example:
        channel_key: email-channel
        index: 0
        rule_type: always
      properties:
        argument:
          description: For conditional rules, the value to compare against.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        channel_key:
          description: The key of the channel this rule applies to.
          type: string
          x-struct: null
          x-validate: null
        index:
          description: The order index of this rule within the channel group.
          type: integer
          x-struct: null
          x-validate: null
        operator:
          description: For conditional rules, the operator to apply.
          enum:
          - equal_to
          - not_equal_to
          - greater_than
          - less_than
          - greater_than_or_equal_to
          - less_than_or_equal_to
          - contains
          - not_contains
          - contains_all
          - not_contains_all
          - is_timestamp_before
          - is_timestamp_on_or_after
          - is_timestamp_between
          - is_between
          - empty
          - not_empty
          - exists
          - not_exists
          - is_timestamp
          - is_audience_member
          - is_not_audience_member
          example: equal_to
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        rule_type:
          description: The type of rule (if = conditional, unless = negative conditional, always = always apply).
          enum:
          - if
          - unless
          - always
          type: string
          x-struct: null
          x-validate: null
        variable:
          description: For conditional rules, the variable to evaluate.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
      required:
      - channel_key
      - rule_type
      title: ChannelGroupRuleRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.ChannelGroupRuleRequest
      x-validate: null
    PreviewWorkflowTemplateResponse:
      description: A response to a preview workflow template request.
      example:
        content_type: email
        result: success
        template:
          html_body: <p>Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} <a href='{{ data.sign_in_url }}'>Get started
            here</a>.</p>
          settings:
            layout_key: default
          subject: Welcome to {{ vars.app_name }}
          text_body: 'Hello, {{ recipient.name }}! Welcome to {{ vars.app_name }} Get started here: {{ data.sign_in_url }}.'
      properties:
        content_type:
          description: The content type of the preview.
          enum:
          - email
          - in_app_feed
          - push
          - chat
          - sms
          - http
          type: string
          x-struct: null
          x-validate: null
        result:
          description: The result of the preview.
          enum:
          - success
          - error
          type: string
          x-struct: null
          x-validate: null
        template:
          anyOf:
          - $ref: '#/components/schemas/EmailTemplate'
          - $ref: '#/components/schemas/InAppFeedTemplate'
          - $ref: '#/components/schemas/PushTemplate'
          - $ref: '#/components/schemas/ChatTemplate'
          - $ref: '#/components/schemas/SmsTemplate'
          - $ref: '#/components/schemas/RequestTemplate'
          description: The rendered template, ready to be previewed.
          type: object
          x-struct: null
          x-validate: null
      required:
      - result
      - content_type
      - template
      title: PreviewWorkflowTemplateResponse
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PreviewWorkflowTemplateResponse
      x-validate: null
    RequestTemplateHeadersString:
      description: A template string that should resolve to a JSON object representing the headers.
      example: '{{ data.request_headers }}'
      title: RequestTemplateHeadersString
      type: string
      x-struct: null
      x-validate: null
    WorkflowUpdateTenantStep:
      description: An update tenant step. Updates properties of a specific tenant referenced in the workflow.
      example:
        description: Update tenant step description.
        name: Update tenant
        ref: update_tenant_1
        settings:
          recipient_gid: gid://Object/$tenants/tenant-123
          recipient_mode: reference
          update_properties: '{"name": "Updated Tenant"}'
        type: update_tenant
      properties:
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - nullable: true
            x-struct: null
            x-validate: null
          description: A conditions object that describes one or more conditions to be met in order for the step to be executed.
          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: Update tenant step description.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Update tenant
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        ref:
          description: The reference key of the workflow step. Must be unique per workflow.
          example: update_tenant_1
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: The settings for the update tenant step.
          properties:
            recipient_gid:
              description: 'The global identifier (GID) of the tenant to update. Required when recipient_mode is ''reference''.
                Format: gid://Object/$tenants/{id}'
              example: gid://Object/$tenants/tenant-123
              nullable: true
              type: string
              x-struct: null
              x-validate: null
            recipient_mode:
              description: The recipient mode determining how the tenant is selected. 'current' uses the workflow's current
                tenant. 'reference' uses a specific tenant ID.
              enum:
              - current
              - reference
              example: reference
              type: string
              x-struct: null
              x-validate: null
            update_properties:
              description: A JSON string or Liquid template that evaluates to the properties to update on the tenant.
              example: '{"name": "Updated Tenant", "status": "active"}'
              type: string
              x-struct: null
              x-validate: null
          required:
          - recipient_mode
          - update_properties
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the workflow step.
          enum:
          - update_tenant
          example: update_tenant
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - ref
      - settings
      title: WorkflowUpdateTenantStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowUpdateTenantStep
      x-validate: null
    WorkflowDelayStep:
      description: A delay function step. Read more in the [docs](https://docs.knock.app/designing-workflows/delay-function).
      example:
        conditions: {}
        description: Delay for 10 seconds
        name: Delay
        ref: delay_step
        settings:
          delay_for:
            unit: seconds
            value: 10
        type: delay
      properties:
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - nullable: true
            x-struct: null
            x-validate: null
          description: A set of conditions to be evaluated for this delay 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: Delay for 10 seconds
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Delay
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        ref:
          description: The reference key of the workflow step. Must be unique per workflow.
          example: delay_step
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: The settings for the delay step. Both fields can be set to compute a delay where `delay_for` is an
            offset from the `delay_until_field_path`.
          properties:
            delay_for:
              anyOf:
              - $ref: '#/components/schemas/Duration'
              - nullable: true
                x-struct: null
                x-validate: null
              description: A duration object that describes how long to wait before proceeding to the next step.
              type: object
              x-struct: null
              x-validate: null
            delay_until_field_path:
              description: When set will use the path to resolve the delay into a timestamp from the property referenced
              example: recipient.delay_until
              type: string
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the workflow step.
          enum:
          - delay
          example: delay
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - ref
      - settings
      title: WorkflowDelayStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowDelayStep
      x-validate: null
    RequestTemplate:
      description: A request template for a fetch function step.
      example:
        body: null
        headers:
        - key: X-API-Key
          value: '1234567890'
        method: get
        query_params:
        - key: key
          value: value
        url: https://example.com
      properties:
        body:
          description: The body of the request. Only used for POST or PUT requests.
          example: '{"key": "value"}'
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        headers:
          description: The headers of the request. Can be a template string or a list of key-value pairs.
          example:
          - key: X-API-Key
            value: '1234567890'
          oneOf:
          - description: A template string that should resolve to a JSON object representing the headers.
            example: '{{ data.request_headers }}'
            title: RequestTemplateHeadersString
            type: string
            x-struct: null
            x-validate: null
          - description: A list of key-value pairs for the request headers. Each object should contain key and value fields
              with string values.
            example:
            - key: X-API-Key
              value: '1234567890'
            items:
              properties:
                key:
                  description: The key of the header.
                  example: X-API-Key
                  type: string
                  x-struct: null
                  x-validate: null
                value:
                  description: The value of the header.
                  example: '1234567890'
                  type: string
                  x-struct: null
                  x-validate: null
              required:
              - key
              - value
              type: object
              x-struct: null
              x-validate: null
            title: RequestTemplateHeadersArray
            type: array
            x-struct: null
            x-validate: null
          title: RequestTemplateHeaders
          type: object
          x-struct: null
          x-validate: null
        method:
          description: The HTTP method of the request.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: post
          type: string
          x-struct: null
          x-validate: null
        query_params:
          description: The query params of the request. Can be a template string or a list of key-value pairs.
          example:
          - key: key
            value: value
          oneOf:
          - description: A template string that should resolve to a JSON object representing the query params.
            example: '{{ data.request_query_params }}'
            title: RequestTemplateQueryParamsString
            type: string
            x-struct: null
            x-validate: null
          - description: A list of key-value pairs for the request query params. Each object should contain key and value
              fields with string values.
            example:
            - key: key
              value: value
            items:
              properties:
                key:
                  description: The key of the query param.
                  example: key
                  type: string
                  x-struct: null
                  x-validate: null
                value:
                  description: The value of the query param.
                  example: value
                  type: string
                  x-struct: null
                  x-validate: null
              required:
              - key
              - value
              type: object
              x-struct: null
              x-validate: null
            title: RequestTemplateQueryParamsArray
            type: array
            x-struct: null
            x-validate: null
          title: RequestTemplateQueryParams
          type: object
          x-struct: null
          x-validate: null
        url:
          description: The URL of the request.
          example: https://example.com
          type: string
          x-struct: null
          x-validate: null
      required:
      - url
      - method
      title: RequestTemplate
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.RequestTemplate
      x-validate: null
    WorkflowBranchStepBranch:
      description: A branch in a branch step.
      example:
        conditions:
          all:
          - argument: pro
            operator: equal_to
            variable: recipient.plan_type
        name: Pro plan
        steps: []
        terminates: false
      properties:
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - nullable: true
            x-struct: null
            x-validate: null
          description: A set of conditions to be evaluated for this branch.
          type: object
          x-struct: null
          x-validate: null
        name:
          description: The name of the branch.
          example: The name of the branch.
          type: string
          x-struct: null
          x-validate: null
        steps:
          description: A list of steps that will be executed if the branch is chosen.
          items:
            $ref: '#/components/schemas/WorkflowStep'
          type: array
          x-struct: null
          x-validate: null
        terminates:
          description: If the workflow should halt at the end of the branch. Defaults to false if not provided.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
      title: WorkflowBranchStepBranch
      type: object
      x-struct: null
      x-validate: null
    PaginatedBranchResponse:
      description: A paginated list of Branch. Contains a list of entries and page information.
      example:
        entries:
        - created_at: '2022-10-31T19:59:03Z'
          deleted_at: null
          last_commit_at: '2022-10-31T19:59:03Z'
          slug: feature-branch
          updated_at: '2022-10-31T19:59:03Z'
        page_info:
          after: null
          before: null
          page_size: 25
      properties:
        entries:
          description: A list of entries.
          items:
            $ref: '#/components/schemas/Branch'
          nullable: false
          type: array
          x-struct: null
          x-validate: null
        page_info:
          $ref: '#/components/schemas/PageInfo'
      required:
      - entries
      - page_info
      title: PaginatedBranchResponse
      type: object
      x-struct: null
      x-validate: null
    GuideScheduledActivationParams:
      description: A request to schedule the activation of a guide. At least one of from or until must be provided.
      example:
        from: '2024-03-20T10:00:00Z'
        until: '2024-03-21T10:00:00Z'
      properties:
        from:
          description: When to activate the guide. If provided, the guide will be scheduled to activate at this time. Must
            be in ISO 8601 UTC format.
          example: '2024-03-20T10:00:00Z'
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        until:
          description: When to deactivate the guide. If provided, the guide will be scheduled to deactivate at this time.
            Must be in ISO 8601 UTC format.
          example: '2024-03-21T10:00:00Z'
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      title: GuideScheduledActivationParams
      type: object
      x-struct: null
      x-validate: null
    WrappedPartialResponse:
      description: Wraps the Partial response under the `partial` key.
      example:
        partial:
          content: <p>Hello, world!</p>
          description: This is a test partial
          environment: development
          icon_name: icon-name
          input_schema:
          - key: text_field
            label: My text field
            settings:
              description: A description of the text field
              max_length: 100
              min_length: 10
              required: true
            type: text
          inserted_at: '2021-01-01T00:00:00Z'
          key: my-partial
          name: My Partial
          type: html
          updated_at: '2021-01-01T00:00:00Z'
          valid: true
          visual_block_enabled: true
      properties:
        partial:
          $ref: '#/components/schemas/Partial'
      required:
      - partial
      title: WrappedPartialResponse
      type: object
      x-struct: null
      x-validate: null
    WorkflowPushStep:
      description: A push step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
      example:
        channel_group_key: null
        channel_key: apns
        channel_overrides: null
        channel_type: push
        conditions: null
        description: This is a description of the channel step
        name: Push channel step
        ref: channel_step
        send_windows: null
        template:
          settings:
            delivery_type: content
            payload_overrides: '{"name": "John"}'
          text_body: Hello, world!
          title: Hello, world!
        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
          nullable: true
          type: string
          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
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        channel_overrides:
          anyOf:
          - $ref: '#/components/schemas/PushChannelSettings'
          - nullable: true
            x-struct: null
            x-validate: null
          description: A map of channel overrides for the channel step.
          type: object
          x-struct: null
          x-validate: null
        channel_type:
          description: The type of the channel step. Always `push` for push steps.
          enum

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