Use audiences to filter your API (AsyncAPI)

Enterprise feature for SDKs

Using this feature in generated SDKs requires the Enterprise plan. To get started, reach out to support@buildwithfern.com.

Audiences are a useful tool for segmenting your event-driven API for different consumers. Common examples of audiences include public and beta.

Tag operations, channels, and message schemas with x-fern-audiences, then filter each output to those audiences: SDKs in generators.yml and your API Reference in docs.yml. Untagged elements are always included; if you don’t specify audiences, nothing is filtered.

Filter operations

Add x-fern-audiences to operations to control which operations are included for specific audiences:

asyncapi.yml

operations:
  sendPublicNotification:
    action: send
    channel:
      $ref: '#/channels/public~1notifications'
    x-fern-audiences:
      - public
  sendBetaAlert:
    action: send
    channel:
      $ref: '#/channels/beta~1alerts'
    x-fern-audiences:
      - beta

Filter channels

You can also filter entire channels by audience:

asyncapi.yml

channels:
  public/events:
    address: public/events
    messages:
      PublicEvent:
        $ref: '#/components/messages/PublicEvent'
    x-fern-audiences:
      - public
  internal/events:
    address: internal/events
    messages:
      InternalEvent:
        $ref: '#/components/messages/InternalEvent'
    x-fern-audiences:
      - internal

Filter message schemas

Filter specific message schemas to different audiences:

asyncapi.yml

components:
  messages:
    PublicUserEvent:
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PublicUser'
      x-fern-audiences:
        - public
    AdminUserEvent:
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AdminUser'
      x-fern-audiences:
        - admin
  schemas:
    PublicUser:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
      x-fern-audiences:
        - public
    AdminUser:
      allOf:
        - $ref: '#/components/schemas/PublicUser'
        - type: object
          properties:
            role:
              type: string
            permissions:
              type: array
              items:
                type: string
      x-fern-audiences:
        - admin

Filter schema properties

You can filter individual properties within schemas:

asyncapi.yml

components:
  schemas:
    UserEvent:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          x-fern-audiences:
            - internal
        publicName:
          type: string
          x-fern-audiences:
            - public
        internalNotes:
          type: string
          x-fern-audiences:
            - internal

This allows you to have different views of the same event schema for different audiences, showing only the relevant information to each consumer.