Knock Broadcasts API

openapi: 3.2.0
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'
                    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:
    WorkflowWebhookStep:
      description: A webhook step within a workflow to send an HTTP request to a generic channel. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
      example:
        channel_group_key: null
        channel_key: pagerduty
        channel_type: http
        conditions: null
        description: This is a description of the channel step
        name: Webhook channel step
        ref: channel_step
        send_windows: null
        template:
          body: null
          headers:
          - key: X-API-Key
            value: '1234567890'
          method: get
          query_params:
          - key: key
            value: value
          url: https://example.com
        type: channel
      properties:
        channel_group_key:
          description: The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.
          example: email
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        channel_key:
          description: The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.
          example: postmark
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        channel_type:
          description: The type of the channel step. Always `http` for webhook steps.
          enum:
          - http
          example: http
          type: string
          x-struct: null
          x-validate: null
        conditions:
          anyOf:
          - $ref: '#/components/schemas/ConditionGroup'
          - x-struct: null
            x-validate: null
          description: A set of conditions to be evaluated for this channel step.
          type: object
          x-struct: null
          x-validate: null
        description:
          description: An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.
          example: Send a message to the channel
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Channel
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ref:
          description: The reference key of the workflow step. Must be unique per workflow.
          example: channel_step
          type: string
          x-struct: null
          x-validate: null
        send_windows:
          description: A list of send window objects. Must include one send window object per day of the week.
          items:
            $ref: '#/components/schemas/SendWindow'
          type:
          - array
          - 'null'
          x-struct: null
          x-validate: null
        template:
          $ref: '#/components/schemas/WebhookTemplate'
        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: WorkflowWebhookStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowWebhookStep
      x-validate: null
    WorkflowBatchStep:
      description: A batch function step. Read more in the [docs](https://docs.knock.app/designing-workflows/batch-function).
      example:
        description: Batch step description
        name: Batch step
        ref: batch_step
        settings:
          batch_key: data.project_id
          batch_window:
            unit: minutes
            value: 10
        type: batch
      properties:
        description:
          description: An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.
          example: Batch step description
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        name:
          description: A name for the workflow step.
          example: Batch step
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ref:
          description: The reference key of the workflow step. Must be unique per workflow.
          example: batch_step
          type: string
          x-struct: null
          x-validate: null
        settings:
          description: The settings for the batch step.
          properties:
            batch_execution_mode:
              description: 'The execution mode of the batch step. One of: `accumulate` or `flush_leading`. When set to `flush_leading`, the first item in the batch will be executed immediately, and the rest will be batched. See [these docs](https://docs.knock.app/designing-workflows/batch-function#immediately-flushing-the-first-item-in-a-batch) for more information.'
              enum:
              - accumulate
              - flush_leading
              example: accumulate
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            batch_items_max_limit:
              description: 'The maximum number of batch items allowed in a batch. Between: 2 and 1000.'
              example: 1000
              type:
              - integer
              - 'null'
              x-struct: null
              x-validate: null
            batch_items_render_limit:
              description: 'The maximum number of batch items allowed to be rendered into a template. Between: 1 and 100. Defaults to 10.'
              example: 10
              type:
              - integer
              - 'null'
              x-struct: null
              x-validate: null
            batch_key:
              description: The data property to use to batch notifications per recipient.
              example: data.project_id
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            batch_order:
              description: 'The order describing whether to return the first or last ten batch items in the activities variable. One of: `asc` or `desc`.'
              enum:
              - asc
              - desc
              example: asc
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            batch_until_field_path:
              description: The data path to resolve the batch window. The resolved value must be an ISO-8601 timestamp.
              example: recipient.batch_until
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
            batch_window:
              anyOf:
              - $ref: '#/components/schemas/Duration'
              - x-struct: null
                x-validate: null
              description: The window of time to collect events in the batch.
              type: object
              x-struct: null
              x-validate: null
            batch_window_extension_limit:
              anyOf:
              - $ref: '#/components/schemas/Duration'
              - x-struct: null
                x-validate: null
              description: A duration object that describes the maximum duration a batch window can be extended to from opening when using a [sliding batch window](https://docs.knock.app/designing-workflows/batch-function#using-a-sliding-batch-window).
              type: object
              x-struct: null
              x-validate: null
            batch_window_type:
              description: 'The type of the batch window used. One of: `fixed` or `sliding`.'
              enum:
              - fixed
              - sliding
              example: fixed
              type:
              - string
              - 'null'
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the workflow step.
          enum:
          - batch
          example: batch
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - ref
      - settings
      title: WorkflowBatchStep
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WorkflowBatchStep
      x-validate: null
    ConditionGroupAnyMatch:
      description: A group of conditions that any must be met. Can contain nested alls.
      example:
        any:
        - all:
          - argument: some_property
            operator: equal_to
            variable: recipient.property
      properties:
        any:
          description: An array of conditions or nested condition groups to evaluate.
          items:
            anyOf:
            - $ref: '#/components/schemas/Condition'
            - $ref: '#/components/schemas/ConditionGroupAllMatch'
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      title: ConditionGroupAnyMatch
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.ConditionGroup.ConditionGroupAnyMatch
      x-validate: null
    EmailMarkdownBlock:
      description: A markdown block in an email template.
      example:
        content: '# Hello, world!'
        layout_attrs:
          padding_bottom: 8
          padding_left: 4
          padding_right: 4
          padding_top: 8
        type: markdown
      properties:
        content:
          description: The markdown content of the block. Supports Liquid templating with variables like `{{ recipient.name }}`, `{{ actor.name }}`, `{{ vars.app_name }}`, `{{ data.custom_field }}`, and `{{ tenant.name }}`. See the [template variables reference](https://docs.knock.app/designing-workflows/template-editor/variables) for available variables.
          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:
            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
          type: object
          x-struct: null
          x-validate: null
        type:
          description: The type of the block.
          enum:
          - markdown
          example: markdown
          type: string
          x-struct: null
          x-validate: null
        variant:
          description: The flavor of markdown to use for the block.
          enum:
          - default
          example: default
          type: strin

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