Use audiences to filter your API (AsyncAPI)

Team and Enterprise feature

This feature is available only for the Team and Enterprise plans. 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

1 operations:
2   sendPublicNotification:
3     action: send
4     channel:
5       $ref: '#/channels/public~1notifications'
6     x-fern-audiences:
7       - public
8   sendBetaAlert:
9     action: send
10     channel:
11       $ref: '#/channels/beta~1alerts'
12     x-fern-audiences:
13       - beta

Filter channels

You can also filter entire channels by audience:

asyncapi.yml

1 channels:
2   public/events:
3     address: public/events
4     messages:
5       PublicEvent:
6         $ref: '#/components/messages/PublicEvent'
7     x-fern-audiences:
8       - public
9   internal/events:
10     address: internal/events
11     messages:
12       InternalEvent:
13         $ref: '#/components/messages/InternalEvent'
14     x-fern-audiences:
15       - internal

Filter message schemas

Filter specific message schemas to different audiences:

asyncapi.yml

1 components:
2   messages:
3     PublicUserEvent:
4       contentType: application/json
5       payload:
6         $ref: '#/components/schemas/PublicUser'
7       x-fern-audiences:
8         - public
9     AdminUserEvent:
10       contentType: application/json
11       payload:
12         $ref: '#/components/schemas/AdminUser'
13       x-fern-audiences:
14         - admin
15   schemas:
16     PublicUser:
17       type: object
18       properties:
19         id:
20           type: string
21         name:
22           type: string
23         email:
24           type: string
25       x-fern-audiences:
26         - public
27     AdminUser:
28       allOf:
29         - $ref: '#/components/schemas/PublicUser'
30         - type: object
31           properties:
32             role:
33               type: string
34             permissions:
35               type: array
36               items:
37                 type: string
38       x-fern-audiences:
39         - admin

Filter schema properties

You can filter individual properties within schemas:

asyncapi.yml

1 components:
2   schemas:
3     UserEvent:
4       type: object
5       properties:
6         id:
7           type: string
8         email:
9           type: string
10           x-fern-audiences:
11             - internal
12         publicName:
13           type: string
14           x-fern-audiences:
15             - public
16         internalNotes:
17           type: string
18           x-fern-audiences:
19             - internal

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