Audiences

Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include public and beta.

Audiences work in two steps: tag elements with audiences in your API spec, then filter your API Reference to the audiences you want in docs.yml using the audience property. To tailor your SDKs the same way, filter them separately in generators.yml.

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

Here’s an example from Schematic in production.

Hide a single field from your API Reference

Audience filtering works at the property level, not just on endpoints and schemas. Tag a field in your spec with an audience your API Reference excludes, and it drops from the docs while the untagged fields around it stay. For example, tag an internalNotes field internal, then filter your API Reference to public in docs.yml, and internalNotes no longer renders.

To remove a field from your docs for all audiences while keeping it in your SDKs, use an OpenAPI overlay instead. To drop it from every Fern output, including docs, SDKs, and the CLI, mark it with x-fern-ignore.

Instance audiences

API Reference audiences work alongside instance audiences, which control which products and versions appear in each documentation instance. You can use both features together:

• API Reference audiences - Control which endpoints and schemas appear within API References
• Instance audiences - Control which products and versions appear in each instance

For example, you might have a public API Reference that shows only public endpoints. To ensure this API Reference only appears on your public documentation site, tag the containing product or version with the public audience.