Document filter property and improve audiences documentation

fern/products/api-def/openapi-pages/extensions/audiences.mdx

@@ -6,47 +6,38 @@ subtitle: Learn how to use x-fern-audiences to filter OpenAPI endpoints, schemas
 
 <Markdown src="/snippets/pro-plan.mdx"/>
 
-Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public`
-and `beta`.
+Fern provides two ways to filter which API elements appear in your SDKs and API Reference docs:
 
-<Info>
-  Remember to filter your SDKs and Docs after specifying audiences. If **no audiences** are specified,
-  nothing will be filtered.
+- **`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.
 
-<AccordionGroup>
+- **`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.
 
-<Accordion title="SDKs">
-The following example configures the SDK to filter to the `public` audience:
+Many teams use both approaches: path-based filtering for major divisions, audience tags for fine-grained control within those divisions.
 
-```yaml title="generators.yml" {3-4}
-groups:
-  sdks:
-    audiences:
-      - public
-    generators:
-      - name: fernapi/fern-typescript-sdk
-        version: 0.8.8
-```
-</Accordion>
+## Path based filtering
 
-<Accordion title="Docs">
-The following example configures the docs to filter to the `public` audience:
+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:
 
-```yaml title="docs.yml" {3-4}
-navigation:
-  - api: API Reference
-    audiences:
-      - public
+```yaml title="generators.yml"
+api:
+  specs:
+    - openapi: "./openapi.yml"
+      settings:
+        filter:
+          endpoints: ["POST /users", "GET /users/{id}"]
 ```
-</Accordion>
 
-</AccordionGroup>
+## Tag based filtering (audiences)
 
-</Info>
+Apply audience tags in your OpenAPI spec, then configure your SDKs or API Reference to filter to those audiences.
 
-## Audiences for servers
+<Steps>
+<Step title="Tag elements in your spec">
 
-To mark a server with a particular audience, add the `x-fern-server-name` and `x-fern-audiences` extension to the relevant server.
+<AccordionGroup>
+<Accordion title="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:
 
@@ -57,10 +48,10 @@ servers:
     x-fern-audiences:
       - public
 ```
+</Accordion>
+<Accordion title="Tag endpoints">
 
-## Audiences for endpoints
-
-To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint.
+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:
 
@@ -72,10 +63,10 @@ paths:
         - public
       operationId: send_email
 ```
+</Accordion>
+<Accordion title="Tag schemas">
 
-## Audiences for schemas
-
-Schemas can be marked for different audiences, as well.
+Add the `x-fern-audiences` extension to the relevant schema.
 
 In this example, the `Email` type is available to both public and beta customers.
 
@@ -96,10 +87,10 @@ components:
         - public
         - beta
 ```
+</Accordion>
+<Accordion title="Tag properties">
 
-## Audiences for properties
-
-Properties can be marked for different audiences, as well.
+Add the `x-fern-audiences` extension to the relevant property.
 
 In this example, the `to` property is available to beta customers only.
 
@@ -119,3 +110,37 @@ components:
           x-fern-audiences:
             - beta
 ```
+</Accordion>
+</AccordionGroup>
+</Step>
+<Step title="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.
+
+<Tabs>
+<Tab title="SDKs">
+The following example configures the SDK to filter to the `public` audience:
+
+```yaml title="generators.yml" {3-4}
+groups:
+  sdks:
+    audiences:
+      - public
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: 0.8.8
+```
+</Tab>
+<Tab title="Docs">
+The following example configures the docs to filter to the `public` audience:
+
+```yaml title="docs.yml" {3-4}
+navigation:
+  - api: API Reference
+    audiences:
+      - public
+```
+</Tab>
+</Tabs>
+</Step>
+</Steps>

fern/products/sdks/guides/filter-your-endpoints-audiences.mdx

@@ -5,235 +5,19 @@ description: Learn how to filter API endpoints using audiences in Fern SDKs. Gen
 
 <Markdown src="/snippets/pro-plan.mdx"/>
 
-Use audiences to generate tailored SDKs for different groups of API consumers. Common examples of audiences include:
-- Internal consumers (e.g., frontend developers who use the API)
-- Beta testers
-- Customers
+Use audiences to generate tailored SDKs for different groups of API consumers, such as internal teams, beta testers, or customers. 
 
-Learn how to use audiences to filter which endpoints are included in your SDKs and documentation.
+Audiences work through tag-based filtering: you tag API elements with audience labels in your spec, then configure which audiences to include when generating SDKs in `generators.yml`. For OpenAPI, [path-based filtering is also available](/learn/api-definitions/openapi/extensions/audiences#path-based-filtering). 
 
+## Get started with audiences
 
-## Configuring audiences
+Choose your API specification format for complete instructions:
 
-For both the Fern Definition and OpenAPI spec, configuring audiences involves:
-1. Marking your API elements with audience tags.
-1. Applying filters in `generators.yml`. Without filtering configuration, all endpoints will
-be included in your SDK regardless of their audience tags. 
-
-
-<AccordionGroup>
-<Accordion title="OpenAPI">
-
-Configuring audiences in an OpenAPI spec involves:
-
-1. Configuring audience extensions for specific servers, endpoints, schemas, and properties.
-1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
-
-<Note>
-    Unlike the Fern Definition, OpenAPI doesn't have a central audience declaration. 
-</Note>
-
-<Steps>
-### Define audiences
-
-OpenAPI uses `x-fern-audiences` to filter to servers, endpoints, schemas and properties.
-
-<AccordionGroup>
-<Accordion title="Servers">
-To mark a server with a particular audience, 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:
-
-```yaml title="openapi.yml" {3-5}
-servers:
-  - url: https://api.com
-    x-fern-server-name: Production
-    x-fern-audiences:
-      - public
-```
-</Accordion>
-<Accordion title="Endpoints">
-To mark an endpoint with a particular audience, 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:
-
-```yaml title="openapi.yml" {4-5}
-paths:
-  /users/sendEmail:
-    post:
-      x-fern-audiences:
-        - public
-      operationId: send_email
-```
-</Accordion>
-<Accordion title="Schemas">
-Schemas can be marked for different audiences, as well.
-
-In this example, the `Email` type is available to both public and beta customers.
-
-```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
-```
-</Accordion>
-<Accordion title="Properties">
-In this example, the `to` property is available to beta customers only.
-
-```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
-```
-</Accordion>
-
-</AccordionGroup>
-
-### Set up SDK filters in `generators.yml`
-
-In `generators.yml`, you can apply audience filters so that only certain
-endpoints are passed to the generators. 
-
-The following example configures the SDK to filter to the `public` audience:
-
-```yaml title="generators.yml" {3-4}
-groups:
-  sdks:
-    audiences:
-      - public
-    generators:
-    ...
-```
-
-### Generate your SDK
-
-  ```bash
-  fern generate --group sdk
-  ```
-
-</Steps>
-</Accordion>
-<Accordion title="Fern Definition">
-
-Configuring audiences in a Fern Definition involves:
-
-1. Explicitly defining audiences in `api.yml`.
-1. Configuring audiences for specific endpoints, types, and properties.
-1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
-
-<Steps>
-### Defining audiences
-
-Audiences are explicitly declared in Fern Definition.
-To use audiences in your Fern Definition, add them to `api.yml`. 
-
-In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:
-
-```yaml title='api.yml' {2-5}
-name: api 
-audiences: 
-  - internal 
-  - beta 
-  - customers
-```
-### Apply audiences to your endpoints, types, and properties
-
-Once you've defined audiences, mark endpoints, types, or properties for a
-particular consumer by adding an `audience` with the relevant groups. 
-
-<AccordionGroup>
-<Accordion title="Endpoints">
-
-In this example, the `sendEmail` endpoint is only available to internal consumers:
-
-```yaml title='user.yml' {6-7}
-service:
-  base-path: /users
-  auth: true
-  endpoints:
-    sendEmail:
-      audiences:
-        - internal
-      path: /send-email
-      ...
-```
-</Accordion>
-<Accordion title="Types">
-
-Types can also be marked for different audiences. 
-
-In this example, the `Email` type is available to internal and beta consumers:
-
-```yaml title='user.yml' {5-7}
-Email: 
-  properties:
-    subject: string
-    body: optional<string>
-  audiences: 
-    - internal
-    - beta
-```
-</Accordion>
-<Accordion title="Properties">
-In this example, the `to` property is available to beta consumers only:
-
-```yaml title='user.yml' {8-9}
-Email: 
-  properties:
-    subject: string
-    body: optional<string>
-    to: 
-      type: string
-      docs: The recipient of the email
-      audiences: 
-        - beta
-```
-</Accordion>
-</AccordionGroup>
-
-### Set up SDK filters in `generators.yml`
-
-In `generators.yml`, you can apply audience filters so that only certain
-endpoints are passed to the generators. 
-
-The following example configures the SDKs to filter for `customers`:
-
-```yaml title='generators.yml' {3-4}
-groups:
-  external:
-    audiences:
-      - customers
-    generators: 
-    ...
-```
-### Generate your SDK
-
-  ```bash
-  fern generate --group sdk
-  ```
-</Steps>
-</Accordion>
-</AccordionGroup>
+<CardGroup cols={2}>
+  <Card title="OpenAPI" href="/learn/api-definitions/openapi/extensions/audiences">
+    Tag elements using `x-fern-audiences`, then configure SDK filtering in `generators.yml`
+  </Card>
+  <Card title="Fern Definition" href="/learn/api-definitions/ferndef/audiences">
+    Declare audiences in `api.yml`, tag elements, then configure SDK filtering in `generators.yml`
+  </Card>
+</CardGroup>