> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Use audiences to filter your API

#### Enterprise feature for SDKs

Using this feature in generated SDKs requires the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto: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](/learn/sdks/reference/generators-yml#openapi) 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`](/learn/api-definitions/openapi/generators-yml-reference#settingsfilter) to limit which endpoints are included in the generated SDK or API Reference based on their paths:

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: "./openapi.yml"
      settings:
        filter:
          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.

#### Tag elements in your spec

#### Tag servers

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`**

```yaml title="openapi.yml" {3-5}
servers:
  - url: https://api.com
    x-fern-server-name: Production
    x-fern-audiences:
      - public
```

#### Tag endpoints

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`**

```yaml title="openapi.yml" {4-5}
paths:
  /users/sendEmail:
    post:
      x-fern-audiences:
        - public
      operationId: send_email
```

#### Tag schemas

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`**

```yaml title="openapi.yml" {13-15}
components:
  schemas:
    Email:
      title: Email
      type: object
      properties:
        subject:
          type: string
        body:
          type: string
        to:
          type: string
      x-fern-audiences:
        - public
        - beta
```

#### Tag properties

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

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

**`openapi.yml`**

```yaml title="openapi.yml" {13-17}
components:
  schemas:
    Email:
      title: Email
      type: object
      properties:
        subject:
          type: string
        body:
          type: string
        to:
          type: string
          x-fern-audiences:
            - beta
```

#### 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`](/learn/docs/api-references/audiences), or your [SDKs in `generators.yml`](/learn/sdks/deep-dives/audiences).
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`](/learn/api-definitions/openapi/generators-yml-reference#settingsfilter) rather than relying on tags alone.

#### Docs

**`docs.yml`**

```yaml title="docs.yml" {3-4}
navigation:
  - api: API Reference
    audiences:
      - public
```

#### SDKs

**`generators.yml`**

```yaml title="generators.yml" {3-4}
groups:
  sdks:
    audiences:
      - public
    generators:
      - name: fern-typescript-sdk
        version: 0.8.8
```

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