OpenAPIExtensions

Use audiences to filter your API

Learn how to use x-fern-audiences to filter OpenAPI endpoints, schemas, and properties for different API consumers like public and beta users.

View as Markdown
Pro and Enterprise feature

This feature is available only for the Pro and Enterprise plans. To get started, reach out to support@buildwithfern.com.

Fern provides two ways to filter which API elements appear in your SDKs and API Reference docs:

  • audiences (tag-based filtering): Tag specific endpoints, schemas, or properties with audience labels, then filter SDKs and Docs to those tags. Best for creating variants based on user types (public vs. beta, free vs. enterprise) or feature maturity, regardless of URL structure.

  • settings.filter (path-based filtering): Filter entire URL paths or patterns. Best when your API organization naturally divides by URL (like /v1/* vs. /v2/*, or /admin/* vs. /user/*). See the settings.filter reference for configuration details.

Many teams use both approaches: path-based filtering for major divisions, audience tags for fine-grained control within those divisions.

Path based filtering

Use settings.filter in your generators.yml to limit which endpoints are included in the generated SDK or API Reference based on their paths:

generators.yml
1api:
2  specs:
3    - openapi: "./openapi.yml"
4      settings:
5        filter:
6          endpoints: ["POST /users", "GET /users/{id}"]

Tag based filtering (audiences)

Apply audience tags in your OpenAPI spec, then configure your SDKs or API Reference to filter to those audiences.

1

Tag elements in your spec

Add the x-fern-server-name and x-fern-audiences extension to the relevant server.

In the example below, the Production server is only available to public consumers:

openapi.yml
1servers:
2  - url: https://api.com
3    x-fern-server-name: Production
4    x-fern-audiences:
5      - public

Add the x-fern-audiences extension to the relevant endpoint.

In the example below, the POST /users/sendEmail endpoint is only available to public consumers:

openapi.yml
1paths:
2  /users/sendEmail:
3    post:
4      x-fern-audiences:
5        - public
6      operationId: send_email

Add the x-fern-audiences extension to the relevant schema.

In this example, the Email type is available to both public and beta customers.

openapi.yml
1components:
2  schemas:
3    Email:
4      title: Email
5      type: object
6      properties:
7        subject:
8          type: string
9        body:
10          type: string
11        to:
12          type: string
13      x-fern-audiences:
14        - public
15        - beta

Add the x-fern-audiences extension to the relevant property.

In this example, the to property is available to beta customers only.

openapi.yml
1components:
2  schemas:
3    Email:
4      title: Email
5      type: object
6      properties:
7        subject:
8          type: string
9        body:
10          type: string
11        to:
12          type: string
13          x-fern-audiences:
14            - beta
2

Filter SDKs or Docs

Specify which audiences to include in your SDKs or API Reference docs. If no audiences are specified, all tagged elements will be included in your SDK regardless of their audience tags.

The following example configures the SDK to filter to the public audience:

generators.yml
1groups:
2  sdks:
3    audiences:
4      - public
5    generators:
6      - name: fernapi/fern-typescript-sdk
7        version: 0.8.8