Knock Audiences API

openapi: 3.2.0
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'
                    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:
    AudienceMemberRequest:
      description: An audience member.
      example:
        tenant: ingen_isla_nublar
        user:
          email: ellie@ingen.net
          id: dr_sattler
          name: Dr. Ellie Sattler
      properties:
        tenant:
          description: The unique identifier for the tenant.
          example: ingen_isla_nublar
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        user:
          allOf:
          - $ref: '#/components/schemas/InlineIdentifyUserRequest'
          description: A user object. At minimum must contain an `id` property.
          x-struct: null
          x-validate: null
      required:
      - user
      title: AudienceMemberRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.AudienceMemberRequest
      x-validate: null
    PreferenceSetChannelTypeSetting:
      description: A set of settings for a channel type. Currently, this can only be a list of conditions to apply.
      example:
        conditions:
        - argument: US
          operator: equal_to
          variable: recipient.country_code
      properties:
        conditions:
          description: A list of conditions to apply to a channel type.
          items:
            $ref: '#/components/schemas/Condition'
          type: array
          x-struct: null
          x-validate: null
      required:
      - conditions
      title: PreferenceSetChannelTypeSetting
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannelTypes.PreferenceSetChannelTypeSetting
      x-validate: null
    MsTeamsTokenConnection:
      description: Microsoft Teams token connection.
      example:
        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
      properties:
        ms_teams_channel_id:
          description: Microsoft Teams channel ID.
          format: uuid
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ms_teams_team_id:
          description: Microsoft Teams team ID.
          format: uuid
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ms_teams_tenant_id:
          description: Microsoft Teams tenant ID.
          format: uuid
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        ms_teams_user_id:
          description: Microsoft Teams user ID.
          format: uuid
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
      title: MsTeamsTokenConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData.TokenConnection
      x-validate: null
    StaticAudience:
      description: A static audience where members are explicitly added or removed via the API.
      example:
        created_at: '2024-01-15T10:30:00Z'
        description: Users participating in the beta program.
        environment: development
        key: beta-testers
        name: Beta testers
        sha: a1b2c3d4e5f6
        type: static
        updated_at: '2024-06-20T14:45:00Z'
      properties:
        created_at:
          description: The timestamp of when the audience was created.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        description:
          description: A description of the audience.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        environment:
          description: The slug of the environment in which the audience exists.
          type: string
          x-struct: null
          x-validate: null
        key:
          description: The unique key of the audience.
          type: string
          x-struct: null
          x-validate: null
        name:
          description: The name of the audience.
          type: string
          x-struct: null
          x-validate: null
        sha:
          description: The SHA hash of the audience data.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        type:
          description: The type of audience. Always `static` for static audiences.
          enum:
          - static
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp of when the audience was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      required:
      - key
      - type
      - name
      - environment
      - created_at
      - updated_at
      title: StaticAudience
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.StaticAudience
      x-validate: null
    InlineIdentifyUserRequest:
      additionalProperties: true
      description: A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
      example:
        channel_data:
          97c5837d-c65c-4d54-aa39-080eeb81c69d:
            tokens:
            - push_token_123
        email: jane@ingen.net
        id: user_1
        name: Jane Doe
        preferences:
          default:
            channel_types:
              email: true
            workflows:
              dinosaurs-loose:
                channel_types:
                  email: true
        timezone: America/New_York
      properties:
        avatar:
          description: A URL for the avatar of the user.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        channel_data:
          allOf:
          - $ref: '#/components/schemas/InlineChannelDataRequest'
          description: Channel-specific information that's needed to deliver a notification to an end provider.
          x-struct: null
          x-validate: null
        created_at:
          description: The creation date of the user from your system.
          format: date-time
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        email:
          description: The primary email address for the user.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        id:
          description: The unique identifier of the user.
          type: string
          x-struct: null
          x-validate: null
        locale:
          description: The locale of the user. Used for [message localization](/concepts/translations).
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        name:
          description: Display name of the user.
          type:
          - string
          - 'null'
          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).
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        preferences:
          allOf:
          - $ref: '#/components/schemas/InlinePreferenceSetRequest'
          description: A set of preferences for the user.
          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).
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
      required:
      - id
      title: InlineIdentifyUserRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineIdentifyUserRequest
      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
    PreferenceSetWorkflowCategorySetting:
      description: Workflow or category preferences within a preference set
      example:
        channel_types:
          email: false
        channels:
          aef6e715-df82-4ab6-b61e-b743e249f7b6: true
      oneOf:
      - example: false
        type: boolean
        x-struct: null
        x-validate: null
      - description: The settings object for a workflow or category, where you can specify channel types or conditions.
        example:
          channel_types:
            email: false
          channels:
            aef6e715-df82-4ab6-b61e-b743e249f7b6: true
          conditions: null
        properties:
          channel_types:
            anyOf:
            - $ref: '#/components/schemas/PreferenceSetChannelTypes'
            - x-struct: null
              x-validate: null
            description: An object where the key is the channel type and the values are the preference settings for that channel type.
            x-struct: null
            x-validate: null
          channels:
            anyOf:
            - $ref: '#/components/schemas/PreferenceSetChannels'
            - x-struct: null
              x-validate: null
            description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
            x-struct: null
            x-validate: null
          conditions:
            description: A list of conditions to apply to a channel type.
            items:
              $ref: '#/components/schemas/Condition'
            type:
            - array
            - 'null'
            x-struct: null
            x-validate: null
        title: PreferenceSetWorkflowCategorySettingObject
        type: object
        x-struct: null
        x-validate: null
      title: PreferenceSetWorkflowCategorySetting
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetWorkflowCategorySetting
      x-validate: null
    StaticAudienceRequest:
      description: Request body for creating/updating a static audience.
      example:
        description: Manually managed list of beta testers
        name: Beta users
        type: static
      properties:
        description:
          description: A description of the audience.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        name:
          description: The name of the audience.
          type: string
          x-struct: null
          x-validate: null
        type:
          description: The type of audience. Set to `static` for static audiences.
          enum:
          - static
          type: string
          x-struct: null
          x-validate: null
      required:
      - type
      - name
      title: StaticAudienceRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.StaticAudienceRequest
      x-validate: null
    OneSignalChannelDataPlayerIdsOnly:
      description: OneSignal channel data.
      example:
        player_ids:
        - 123e4567-e89b-12d3-a456-426614174000
      properties:
        player_ids:
          description: A list of OneSignal player IDs.
          example:
          - 123e4567-e89b-12d3-a456-426614174000
          items:
            description: OneSignal player ID.
            format: uuid
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
      required:
      - player_ids
      title: OneSignalChannelDataPlayerIdsOnly
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.OneSignalChannelDataPlayerIdsOnly
      x-validate: null
    RemoveAudienceMembersRequest:
      description: A request to remove a list of audience members.
      example:
        members:
        - tenant: ingen_isla_nublar
          user:
            email: ellie@ingen.net
            id: dr_sattler
            name: Dr. Ellie Sattler
      properties:
        members:
          description: A list of audience members to remove. You can remove up to 1,000 members per request.
          items:
            $ref: '#/components/schemas/AudienceMemberRequest'
          type: array
          x-struct: null
          x-validate: null
      required:
      - members
      title: RemoveAudienceMembersRequest
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.RemoveAudienceMembersRequest
      x-validate: null
    AudienceMember:
      description: An audience member.
      example:
        __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
      properties:
        __typename:
          description: The typename of the schema.
          example: AudienceMember
          type: string
          x-struct: null
          x-validate: null
        added_at:
          description: Timestamp when the resource was created.
          example: '2025-01-01T00:00:00Z'
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        tenant:
          description: The unique identifier for the tenant.
          example: acme_corp
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        user:
          $ref: '#/components/schemas/User'
        user_id:
          description: The unique identifier of the user.
          example: user_123
          type: string
          x-struct: null
          x-validate: null
      required:
      - __typename
      - added_at
      - user_id
      - user
      title: AudienceMember
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.AudienceMember
      x-validate: null
    DiscordChannelConnection:
      description: Discord channel connection.
      example:
        channel_id: '123456789012345678'
      properties:
        channel_id:
          description: Discord channel ID.
          example: '123456789012345678'
          type: string
          x-struct: null
          x-validate: null
      required:
      - channel_id
      title: DiscordChannelConnection
      type: object
      x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.ChannelConnection
      x-validate: null
    Condition:
      description: A condition to be evaluated.
      example:
        argument: frog_genome
        operator: contains
        variable: 

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