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
Team and Enterprise feature

This feature is available only for the Team 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 elements are included regardless of their tags.

When you do specify audiences, elements tagged with a matching audience are included, and elements tagged only with other audiences are dropped. Untagged elements aren’t scoped to any audience, so they’re always included. This is what lets you hide a single field: a property tagged only beta drops from a public output, while the untagged properties around it stay.

Set the filter where each output is configured: your API Reference in docs.yml, or your SDKs in generators.yml. Specify which audiences to include in your SDKs or API Reference docs.

Filtering is inclusive by default: it applies only where you set audiences. A group or navigation entry with no audiences receives the full spec, and an element with no tags is included for every audience.

To keep internal endpoints out of partner-facing output entirely, split them into a separate API definition or exclude their paths with settings.filter rather than relying on tags alone.

docs.yml
1navigation:
2  - api: API Reference
3    audiences:
4      - public