Audiences

Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include public and beta. You can configure audiences in the OpenAPI Specification.

Once you’ve added audiences to your API Specification, you can filter to that audience by adding the audience property to the api object in your docs.yml navigation.

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

Here’s an example from Schematic in production.

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.