Knock Broadcasts API

openapi: 3.0.3
info:
  title: Knock Audiences Accounts Broadcasts 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:
- name: Broadcasts
paths:
  /v1/broadcasts/{broadcast_key}/send:
    put:
      callbacks: {}
      description: 'Sends a broadcast immediately or schedules it to send at a future time.

        '
      operationId: sendBroadcast
      parameters:
      - description: The key of the broadcast.
        in: path
        name: broadcast_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/BroadcastSendRequest'
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Broadcast response under the `broadcast` key.
                example:
                  broadcast:
                    categories:
                    - marketing
                    - promotions
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: Holiday promotion broadcast for December
                    environment: development
                    key: december-promotion
                    name: December Promotion
                    scheduled_at: null
                    sent_at: null
                    settings:
                      is_commercial: true
                      override_preferences: false
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    status: draft
                    steps:
                    - channel_key: in-app-feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ vars.app_url }}'
                        markdown_body: Hello **{{ recipient.name }}**
                      type: channel
                    target_audience_key: premium-users
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  broadcast:
                    $ref: '#/components/schemas/Broadcast'
                required:
                - broadcast
                title: WrappedBroadcastResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Send a broadcast
      tags:
      - Broadcasts
  /v1/broadcasts/{broadcast_key}/validate:
    put:
      callbacks: {}
      description: 'Validates a broadcast payload without persisting it.

        '
      operationId: validateBroadcast
      parameters:
      - description: The key of the broadcast.
        in: path
        name: broadcast_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 BroadcastRequest request under the broadcast key.
              example:
                broadcast:
                  categories:
                  - announcement
                  description: A broadcast to all users
                  name: My Broadcast
                  settings:
                    is_commercial: true
                    override_preferences: false
                  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
                  target_audience_key: all-users
              properties:
                broadcast:
                  $ref: '#/components/schemas/BroadcastRequest'
              required:
              - broadcast
              title: WrappedBroadcastRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Broadcast response under the `broadcast` key.
                example:
                  broadcast:
                    categories:
                    - marketing
                    - promotions
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: Holiday promotion broadcast for December
                    environment: development
                    key: december-promotion
                    name: December Promotion
                    scheduled_at: null
                    sent_at: null
                    settings:
                      is_commercial: true
                      override_preferences: false
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    status: draft
                    steps:
                    - channel_key: in-app-feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ vars.app_url }}'
                        markdown_body: Hello **{{ recipient.name }}**
                      type: channel
                    target_audience_key: premium-users
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  broadcast:
                    $ref: '#/components/schemas/Broadcast'
                required:
                - broadcast
                title: WrappedBroadcastResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate a broadcast
      tags:
      - Broadcasts
  /v1/broadcasts:
    get:
      callbacks: {}
      description: Returns a paginated list of broadcasts available in a given environment. The broadcasts are returned ordered by creation time (newest first).
      operationId: listBroadcasts
      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 Broadcast. Contains a list of entries and page information.
                example:
                  entries:
                  - categories:
                    - marketing
                    - promotions
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: Holiday promotion broadcast for December
                    environment: development
                    key: december-promotion
                    name: December Promotion
                    scheduled_at: null
                    sent_at: null
                    settings:
                      is_commercial: true
                      override_preferences: false
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    status: draft
                    steps:
                    - channel_key: in-app-feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ vars.app_url }}'
                        markdown_body: Hello **{{ recipient.name }}**
                      type: channel
                    target_audience_key: premium-users
                    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/Broadcast'
                    nullable: false
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedBroadcastResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List broadcasts
      tags:
      - Broadcasts
  /v1/broadcasts/{broadcast_key}:
    get:
      callbacks: {}
      description: Get a broadcast by its key in a given environment.
      operationId: getBroadcast
      parameters:
      - description: The key of the broadcast to retrieve.
        in: path
        name: broadcast_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/Broadcast'
          description: OK
      summary: Get a broadcast
      tags:
      - Broadcasts
    put:
      callbacks: {}
      description: 'Updates a broadcast of a given key, or creates a new one if it does not yet exist.

        '
      operationId: upsertBroadcast
      parameters:
      - description: The key of the broadcast.
        in: path
        name: broadcast_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
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the BroadcastRequest request under the broadcast key.
              example:
                broadcast:
                  categories:
                  - announcement
                  description: A broadcast to all users
                  name: My Broadcast
                  settings:
                    is_commercial: true
                    override_preferences: false
                  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
                  target_audience_key: all-users
              properties:
                broadcast:
                  $ref: '#/components/schemas/BroadcastRequest'
              required:
              - broadcast
              title: WrappedBroadcastRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Broadcast response under the `broadcast` key.
                example:
                  broadcast:
                    categories:
                    - marketing
                    - promotions
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: Holiday promotion broadcast for December
                    environment: development
                    key: december-promotion
                    name: December Promotion
                    scheduled_at: null
                    sent_at: null
                    settings:
                      is_commercial: true
                      override_preferences: false
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    status: draft
                    steps:
                    - channel_key: in-app-feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ vars.app_url }}'
                        markdown_body: Hello **{{ recipient.name }}**
                      type: channel
                    target_audience_key: premium-users
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  broadcast:
                    $ref: '#/components/schemas/Broadcast'
                required:
                - broadcast
                title: WrappedBroadcastResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert a broadcast
      tags:
      - Broadcasts
  /v1/broadcasts/{broadcast_key}/cancel:
    put:
      callbacks: {}
      description: 'Cancels sending a scheduled broadcast. The broadcast will return to draft status.

        '
      operationId: cancelBroadcast
      parameters:
      - description: The key of the broadcast.
        in: path
        name: broadcast_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
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Broadcast response under the `broadcast` key.
                example:
                  broadcast:
                    categories:
                    - marketing
                    - promotions
                    created_at: '2022-12-16T19:07:50.027113Z'
                    description: Holiday promotion broadcast for December
                    environment: development
                    key: december-promotion
                    name: December Promotion
                    scheduled_at: null
                    sent_at: null
                    settings:
                      is_commercial: true
                      override_preferences: false
                    sha: f7e9d3b2a1c8e6m4k5j7h9g0i2l3n4p6q8r0t1u3v5w7x9y
                    status: draft
                    steps:
                    - channel_key: in-app-feed
                      description: Main in-app feed
                      name: In-app step
                      ref: in_app_feed_1
                      template:
                        action_url: '{{ vars.app_url }}'
                        markdown_body: Hello **{{ recipient.name }}**
                      type: channel
                    target_audience_key: premium-users
                    updated_at: '2023-02-08T22:15:19.846681Z'
                    valid: true
                properties:
                  broadcast:
                    $ref: '#/components/schemas/Broadcast'
                required:
                - broadcast
                title: WrappedBroadcastResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Cancel a scheduled broadcast
      tags:
      - Broadcasts
components:
  schemas:
    WorkflowRandomCohortStepBranch:
      description: A cohort branch in an experiment step.
      example:
        name: Control
        percentage: '50'
        steps: []
        terminates: false
      properties:
        name:
          description: The name of the cohort branch.
          example: Control
          type: string
          x-struct: null
          x-validate: null
        percentage:
          description: The percentage of recipients to assign to this cohort. Must be between 0 and 100 with at most 1 decimal place. All branch percentages must sum to 100. Sent as a number in requests; returned as a decimal string in responses (e.g. "50", "33.3").
          example: '50'
          type: string
          x-struct: null
          x-validate: null
        steps:
          description: A list of steps that will be executed for recipients assigned to this cohort.
          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: false
          type: boolean
          x-struct: null
          x-validate: null
      required:
      - percentage
      title: WorkflowRandomCohortStepBranch
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowRandomCohortStep.CohortBranch
      x-validate: null
    ConditionGroup:
      anyOf:
      - $ref: '#/components/schemas/ConditionGroupAllMatch'
      - $ref: '#/components/schemas/ConditionGroupAnyMatch'
      description: A group of conditions to be evaluated.
      example:
        all:
        - argument: some_property
          operator: equal_to
          variable: recipient.property
      title: ConditionGroup
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.ConditionGroup
      x-validate: null
    PushChannelSettings:
      description: Push channel settings. Only used as configuration as part of a workflow channel step.
      example:
        token_deregistration: true
      properties:
        token_deregistration:
          description: Whether to deregister a push-token when a push send hard bounces. This is to prevent the same token from being used for future pushes.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
      title: PushChannelSettings
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PushChannelSettings
      x-validate: null
    WorkflowChatStep:
      description: A chat step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
      example:
        channel_group_key: null
        channel_key: slack
        channel_overrides: null
        channel_type: chat
        conditions: null
        description: This is a description of the channel step
        name: Chat channel step
        ref: channel_step
        send_windows: null
        template:
          json_body: null
          markdown_body: '**Hello**, world!'
          summary: 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/ChatChannelSettings'
          - 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 `chat` for chat steps.
          enum:
          - chat
          example: chat
          type: string
          x-struct: null
          x-validate: null
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - nullable: true
            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
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Channel
          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: 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'
          nullable: true
          type: array
          x-struct: null
          x-validate: null
        template:
          $ref: '#/components/schemas/ChatTemplate'
        type:
          description: The type of the workflow step.
          enum:
          - channel
          example: channel
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - ref
      - template
      title: WorkflowChatStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowChatStep
      x-validate: null
    ChatChannelSettings:
      description: Chat channel settings. Only used as configuration as part of a workflow channel step.
      example:
        email_based_user_id_resolution: true
        link_tracking: true
      properties:
        email_based_user_id_resolution:
          description: Whether to resolve chat provider user IDs using a Knock user's email address. Only relevant for Slack channels for the time being.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
        link_tracking:
          description: Whether to track link clicks on chat notifications.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
      title: ChatChannelSettings
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.ChatChannelSettings
      x-validate: null
    EmailChannelSettings:
      description: Email channel settings. Only used as configuration as part of a workflow channel step.
      example:
        bcc_address: null
        cc_address: null
        from_address: hello@example.com
        from_name: John Doe
        json_overrides: '{"some_override": true}'
        link_tracking: true
        open_tracking: true
        reply_to_address: null
        to_address: hello@example.com
      properties:
        bcc_address:
          description: The BCC address on email notifications. Supports liquid.
          example: hello@example.com
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        cc_address:
          description: The CC address on email notifications. Supports liquid.
          example: hello@example.com
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        from_address:
          description: The email address from which this channel will send. Supports liquid.
          example: hello@example.com
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        from_name:
          description: The name from which this channel will send. Supports liquid.
          example: John Doe
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        json_overrides:
          description: A JSON template for any custom overrides to merge into the API payload that is sent to the email provider. Supports liquid.
          example: '{"some_override": true}'
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        link_tracking:
          description: Whether to track link clicks on email notifications.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
        open_tracking:
          description: Whether to track opens on email notifications.
          example: true
          type: boolean
          x-struct: null
          x-validate: null
        reply_to_address:
          description: The Reply-to address on email notifications. Supports liquid.
          example: hello@example.com
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        to_address:
          description: The email address to which this channel will send. Defaults to `recipient.email`. Supports liquid.
          example: hello@example.com
          type: string
          x-struct: null
          x-validate: null
      title: EmailChannelSettings
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.EmailChannelSettings
      x-validate: null
    WorkflowFetchStep:
      description: A fetch function step. Retrieves data from an external source and merges it into the workflow's `data` scope for use in later steps. Read more in the [docs](https://docs.knock.app/designing-workflows/fetch-function).
      example:
        name: Fetch step
        ref: fetch_1
        settings:
          body: null
          headers:
          - key: X-API-Key
            value: '1234567890'
          method: get
          query_params:
          - key: key
            value: value
          url: https://example.com
        type: http_fetch
      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: Fetch step description
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Fetch step
          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: fetch_step
          type: string
          x-struct: null
          x-validate: null
        settings:
          $ref: '#/components/schemas/RequestTemplate'
        type:
          description: The type of the workflow step.
          enum:
          - http_fetch
          example: http_fetch
          type: string
          x-struct: null
          x-validate: null
      required:
      - type

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