Knock Audiences API

openapi: 3.0.3
info:
  title: Knock Accounts Audiences 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: Audiences
paths:
  /v1/audiences/{key}/members:
    delete:
      callbacks: {}
      description: Removes one or more members from the specified audience.
      operationId: removeAudienceMembers
      parameters:
      - description: The key of the audience.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveAudienceMembersRequest'
        description: Params
        required: true
      responses:
        '204':
          description: No Content
      summary: Remove members
      tags:
      - Audiences
      x-ratelimit-tier: 3
    get:
      callbacks: {}
      description: Returns a paginated list of members for the specified audience.
      operationId: listAudienceMembers
      parameters:
      - description: The key of the audience.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAudienceMembersResponse'
          description: OK
      summary: List members
      tags:
      - Audiences
      x-ratelimit-tier: 4
    post:
      callbacks: {}
      description: Adds one or more members to the specified audience.
      operationId: addAudienceMembers
      parameters:
      - description: The key of the audience.
        in: path
        name: key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Create the audience if it does not exist.
        in: query
        name: create_audience
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            example:
              members:
              - tenant: ingen_isla_nublar
                user:
                  email: ellie@ingen.net
                  id: dr_sattler
                  name: Dr. Ellie Sattler
            schema:
              $ref: '#/components/schemas/AddAudienceMembersRequest'
        description: Params
        required: true
      responses:
        '204':
          description: No Content
      summary: Add members
      tags:
      - Audiences
      x-ratelimit-tier: 3
  /v1/audiences/{audience_key}:
    delete:
      callbacks: {}
      description: Archives a given audience across all environments.
      operationId: archiveAudience
      parameters:
      - description: The key of the audience to archive.
        in: path
        name: audience_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
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The response from archiving an audience.
                example:
                  result: success
                properties:
                  result:
                    description: The result of the archive operation.
                    example: success
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                - result
                title: ArchiveAudienceResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Archive an audience
      tags:
      - Audiences
    get:
      callbacks: {}
      description: Retrieve an audience by its key in a given environment.
      operationId: getAudience
      parameters:
      - description: The key of the audience to retrieve.
        in: path
        name: audience_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/Audience'
          description: OK
      summary: Get an audience
      tags:
      - Audiences
    put:
      callbacks: {}
      description: Updates an audience of a given key, or creates a new one if it does not yet exist.
      operationId: upsertAudience
      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 key of the audience to upsert.
        in: path
        name: audience_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks.
        in: query
        name: force
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to commit the resource at the same time as modifying it.
        in: query
        name: commit
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The message to commit the resource with, only used if `commit` is `true`.
        in: query
        name: commit_message
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the AudienceRequest request under the audience key.
              example:
                audience:
                  description: Users on the premium plan
                  name: Premium users
                  segments:
                  - conditions:
                    - argument: premium
                      operator: equal_to
                      property: recipient.plan
                  type: dynamic
              properties:
                audience:
                  $ref: '#/components/schemas/AudienceRequest'
              required:
              - audience
              title: WrappedAudienceRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Audience response under the `audience` key.
                example:
                  audience:
                    created_at: '2024-01-15T10:30:00Z'
                    description: Customers who signed up in the last 30 days.
                    environment: development
                    key: new-customers
                    name: New customers
                    segments:
                    - conditions:
                      - argument: 30_days_ago
                        operator: greater_than
                        property: recipient.created_at
                    sha: a1b2c3d4e5f6
                    type: dynamic
                    updated_at: '2024-06-20T14:45:00Z'
                properties:
                  audience:
                    $ref: '#/components/schemas/Audience'
                required:
                - audience
                title: WrappedAudienceResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert an audience
      tags:
      - Audiences
  /v1/audiences/{audience_key}/validate:
    put:
      callbacks: {}
      description: Validates an audience payload without persisting it.
      operationId: validateAudience
      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 key of the audience to validate.
        in: path
        name: audience_key
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the AudienceRequest request under the audience key.
              example:
                audience:
                  description: Users on the premium plan
                  name: Premium users
                  segments:
                  - conditions:
                    - argument: premium
                      operator: equal_to
                      property: recipient.plan
                  type: dynamic
              properties:
                audience:
                  $ref: '#/components/schemas/AudienceRequest'
              required:
              - audience
              title: WrappedAudienceRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Audience response under the `audience` key.
                example:
                  audience:
                    created_at: '2024-01-15T10:30:00Z'
                    description: Customers who signed up in the last 30 days.
                    environment: development
                    key: new-customers
                    name: New customers
                    segments:
                    - conditions:
                      - argument: 30_days_ago
                        operator: greater_than
                        property: recipient.created_at
                    sha: a1b2c3d4e5f6
                    type: dynamic
                    updated_at: '2024-06-20T14:45:00Z'
                properties:
                  audience:
                    $ref: '#/components/schemas/Audience'
                required:
                - audience
                title: WrappedAudienceResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate an audience
      tags:
      - Audiences
  /v1/audiences:
    get:
      callbacks: {}
      description: Returns a paginated list of audiences for the given environment.
      operationId: listAudiences
      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 Audience. Contains a list of entries and page information.
                example:
                  entries:
                  - created_at: '2024-01-15T10:30:00Z'
                    description: Customers who signed up in the last 30 days.
                    environment: development
                    key: new-customers
                    name: New customers
                    segments:
                    - conditions:
                      - argument: 30_days_ago
                        operator: greater_than
                        property: recipient.created_at
                    sha: a1b2c3d4e5f6
                    type: dynamic
                    updated_at: '2024-06-20T14:45:00Z'
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Audience'
                    nullable: false
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo_2'
                required:
                - entries
                - page_info
                title: PaginatedAudienceResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List audiences
      tags:
      - Audiences
components:
  schemas:
    SlackTokenConnection:
      description: A Slack connection token.
      example:
        access_token: xoxb-1234567890
        channel_id: C01234567890
        user_id: U01234567890
      properties:
        access_token:
          description: A Slack access token.
          example: xoxb-1234567890
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        channel_id:
          description: A Slack channel ID from the Slack provider.
          example: C01234567890
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        user_id:
          description: A Slack user ID from the Slack provider.
          example: U01234567890
          nullable: true
          type: string
          x-struct: null
          x-validate: null
      title: SlackTokenConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.SlackChannelData.TokenConnection
      x-validate: null
    ListAudienceMembersResponse:
      description: A paginated list of audience members.
      example:
        entries:
        - __typename: AudienceMember
          added_at: '1993-06-10T14:30:00Z'
          tenant: ingen_isla_nublar
          user:
            __typename: User
            created_at: null
            email: alan.grant@dig.site.mt
            id: dr_grant
            name: Dr. Alan Grant
            updated_at: '1993-06-09T08:15:00Z'
          user_id: dr_grant
        page_info:
          __typename: PageInfo
          after: null
          before: null
          page_size: 25
      properties:
        entries:
          description: A list of audience members.
          items:
            $ref: '#/components/schemas/AudienceMember'
          type: array
          x-struct: null
          x-validate: null
        page_info:
          $ref: '#/components/schemas/PageInfo'
      required:
      - entries
      - page_info
      title: ListAudienceMembersResponse
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.ListAudienceMembersResponse
      x-validate: null
    PushChannelDataTokensOnly:
      description: Push channel data.
      example:
        tokens:
        - push_token_1
        - push_token_2
      properties:
        tokens:
          description: A list of push channel tokens.
          items:
            description: The device token to send the push notification to.
            nullable: false
            type: string
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
      required:
      - tokens
      title: PushChannelDataTokensOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PushChannelDataTokensOnly
      x-validate: null
    InlinePreferenceSetRequest:
      additionalProperties:
        $ref: '#/components/schemas/PreferenceSetRequest'
      description: Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
      example:
        default:
          categories:
            transactional:
              channel_types:
                email: false
          channel_types:
            email: true
      title: InlinePreferenceSetRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.InlinePreferenceSetRequest
      x-validate: null
    User:
      additionalProperties: true
      description: A [User](/concepts/users) represents an individual in your system who can receive notifications through Knock. Users are the most common recipients of notifications and are always referenced by your internal identifier.
      example:
        __typename: User
        created_at: null
        email: ian.malcolm@chaos.theory
        id: user_id
        name: Dr. Ian Malcolm
        updated_at: '2024-05-22T12:00:00Z'
      properties:
        __typename:
          description: The typename of the schema.
          example: User
          type: string
          x-struct: null
          x-validate: null
        avatar:
          description: A URL for the avatar of the user.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        created_at:
          description: The creation date of the user from your system.
          format: date-time
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        email:
          description: The primary email address for the user.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        id:
          description: The unique identifier of the user.
          type: string
          x-struct: null
          x-validate: null
        name:
          description: Display name of the user.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        phone_number:
          description: The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        timezone:
          description: The timezone of the user. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp when the resource was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      required:
      - __typename
      - id
      - updated_at
      title: User
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.User
      x-validate: null
    DynamicAudienceRequest:
      description: Request body for creating/updating a dynamic audience.
      example:
        description: Users on the premium plan
        name: Premium users
        segments:
        - conditions:
          - argument: premium
            operator: equal_to
            property: recipient.plan
        type: dynamic
      properties:
        description:
          description: A description of the audience.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        name:
          description: The name of the audience.
          type: string
          x-struct: null
          x-validate: null
        segments:
          description: A list of segments that define the dynamic audience membership criteria. Each segment contains one or more conditions joined by AND. Multiple segments are joined by OR.
          items:
            properties:
              conditions:
                description: A list of conditions within this segment, joined by AND.
                items:
                  $ref: '#/components/schemas/AudienceCondition'
                type: array
                x-struct: null
                x-validate: null
            required:
            - conditions
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
        type:
          description: The type of audience. Set to `dynamic` for dynamic audiences.
          enum:
          - dynamic
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - name
      title: DynamicAudienceRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.DynamicAudienceRequest
      x-validate: null
    PreferenceSetChannels:
      additionalProperties:
        description: Whether the specific channel (by channel_id) is enabled for the preference set, or a settings object with conditions.
        oneOf:
        - type: boolean
          x-struct: null
          x-validate: null
        - $ref: '#/components/schemas/PreferenceSetChannelSetting'
        x-struct: null
        x-validate: null
      description: Channel preferences.
      example:
        2f641633-95d3-4555-9222-9f1eb7888a80:
          conditions:
          - argument: US
            operator: equal_to
            variable: recipient.country_code
        aef6e715-df82-4ab6-b61e-b743e249f7b6: true
      title: PreferenceSetChannels
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannels
      x-validate: null
    SlackIncomingWebhookConnection:
      description: A Slack connection incoming webhook.
      example:
        url: https://hooks.slack.com/services/T01234567890/B01234567890/1234567890
      properties:
        url:
          description: The URL of the incoming webhook for a Slack connection.
          example: https://hooks.slack.com/services/T01234567890/B01234567890/1234567890
          nullable: false
          type: string
          x-struct: null
          x-validate: null
      required:
      - url
      title: SlackIncomingWebhookConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.SlackChannelData.IncomingWebhookConnection
      x-validate: null
    InlineChannelDataRequest:
      additionalProperties:
        description: Channel data for a given channel type.
        nullable: false
        oneOf:
        - $ref: '#/components/schemas/PushChannelDataTokensOnly'
        - $ref: '#/components/schemas/PushChannelDataDevicesOnly'
        - $ref: '#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly'
        - $ref: '#/components/schemas/AWSSNSPushChannelDataDevicesOnly'
        - $ref: '#/components/schemas/OneSignalChannelDataPlayerIdsOnly'
        - $ref: '#/components/schemas/SlackChannelData'
        - $ref: '#/components/schemas/MsTeamsChannelData'
        - $ref: '#/components/schemas/DiscordChannelData'
        x-struct: null
        x-validate: null
      description: A request to set channel data for a type of channel inline.
      example:
        97c5837d-c65c-4d54-aa39-080eeb81c69d:
          tokens:
          - push_token_xxx
      title: InlineChannelDataRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineChannelDataRequest
      x-validate: null
    PushChannelDataDevicesOnly:
      description: Push channel data.
      example:
        devices:
        - locale: en-US
          timezone: America/Los_Angeles
          token: push_token_1
      properties:
        devices:
          description: A list of devices. Each device contains a token, and optionally a locale and timezone.
          items:
            properties:
              locale:
                description: The locale of the object. Used for [message localization](/concepts/translations).
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              timezone:
                description: The timezone of the object. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              token:
                description: The device token to send the push notification to.
                type: string
                x-struct: null
                x-validate: null
            required:
            - token
            type: object
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
      required:
      - devices
      title: PushChannelDataDevicesOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PushChannelDataDevicesOnly
      x-validate: null
    DiscordChannelData:
      description: Discord channel data.
      example:
        connections:
        - channel_id: '123456789012345678'
      properties:
        connections:
          description: List of Discord channel connections.
          items:
            description: Discord channel connection, either a channel connection or an incoming webhook connection.
            oneOf:
            - $ref: '#/components/schemas/DiscordChannelConnection'
            - $ref: '#/components/schemas/DiscordIncomingWebhookConnection'
            type: object
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
      required:
      - connections
      title: DiscordChannelData
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData
      x-validate: null
    MsTeamsChannelData:
      description: Microsoft Teams channel data.
      example:
        connections:
        - ms_teams_channel_id: 123e4567-e89b-12d3-a456-426614174000
          ms_teams_team_id: 123e4567-e89b-12d3-a456-426614174000
          ms_teams_tenant_id: null
          ms_teams_user_id: null
        ms_teams_tenant_id: null
      properties:
        connections:
          description: List of Microsoft Teams connections.
          items:
            oneOf:
            - $ref: '#/components/schemas/MsTeamsTokenConnection'
            - $ref: '#/components/schemas/MsTeamsIncomingWebhookConnection'
            type: object
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
        ms_teams_tenant_id:
          description: Microsoft Teams tenant ID.
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          nullable: true
          type: string
          x-struct: null
          x-validate: null
      required:
      - connections
      title: MsTeamsChannelData
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData
      x-validate: null
    SlackChannelData:
      description: Slack channel data.
      example:
        connections:
        - access_token: xoxb-1234567890
          channel_id: C01234567890
          user_id: U01234567890
        token:
          access_token: xoxb-1234567890
      properties:
        connections:
          description: List of Slack channel connections.
          items:
            description: A Slack connection, either an access token or an incoming webhook
            nullable: false
            oneOf:
            - $ref: '#/components/schemas/SlackTokenConnection'
            - $ref: '#/components/schemas/SlackIncomingWebhookConnection'
            type: object
            x-struct: null
            x-validate: null
          nullable: false
          type: array
          x-struct: null
          x-validate: null
        token:
          description: A Slack connection token.
          example:
            access_token: xoxb-1234567890
          nullable: true
          properties:
            access_token:
              description: A Slack access token.
              example: xoxb-1234567890
              nullable: true
              type: string
              x-struct: null
              x-validate: null
          required:
          - access_token
          title: SlackChannelDataTokenObject
          type: object
          x-struct: null
          x-validate: null
      required:
 

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