Use audiences to filter your API (OpenRPC)

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

Tag methods, parameters, and schemas with x-fern-audiences, then filter each output to those audiences: SDKs in generators.yml and your API Reference in docs.yml. Untagged elements are always included; if you don’t specify audiences, nothing is filtered.

Filter methods

Add x-fern-audiences to methods to control which methods are included for specific audiences:

openrpc.yml

methods:
  - name: public.getInfo
    summary: Get public API information
    description: Publicly available information about the API
    x-fern-audiences:
      - public
    params: []
    result:
      name: info
      schema:
        $ref: '#/components/schemas/ApiInfo'
  - name: admin.getUsers
    summary: Get all users (admin only)
    x-fern-audiences:
      - admin
    params:
      - name: limit
        schema:
          type: integer
          default: 100
    result:
      name: users
      schema:
        type: array
        items:
          $ref: '#/components/schemas/User'

Filter method parameters

You can filter specific parameters within methods:

openrpc.yml

methods:
  - name: user.create
    summary: Create a new user
    params:
      - name: userData
        schema:
          type: object
          properties:
            email:
              type: string
              format: email
            name:
              type: string
            adminNotes:
              type: string
              x-fern-audiences:
                - admin
            internalId:
              type: string
              x-fern-audiences:
                - internal
          required:
            - email
            - name
        required: true
    result:
      name: user
      schema:
        $ref: '#/components/schemas/User'

Filter schemas

Filter entire schemas to different audiences:

openrpc.yml

components:
  schemas:
    PublicUser:
      type: object
      x-fern-audiences:
        - public
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name
        - email
    AdminUser:
      allOf:
        - $ref: '#/components/schemas/PublicUser'
        - type: object
          x-fern-audiences:
            - admin
          properties:
            role:
              type: string
            permissions:
              type: array
              items:
                type: string
            createdAt:
              type: string
              format: date-time
            lastLoginAt:
              type: string
              format: date-time

Filter schema properties

You can filter individual properties within schemas:

openrpc.yml

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          x-fern-audiences:
            - public
        internalCost:
          type: number
          x-fern-audiences:
            - internal
        debugInfo:
          type: object
          x-fern-audiences:
            - debug
        customerInfo:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
              x-fern-audiences:
                - admin

Filter error responses

Filter error information based on audience:

openrpc.yml

methods:
  - name: payment.process
    summary: Process a payment
    params:
      - name: paymentData
        schema:
          $ref: '#/components/schemas/PaymentRequest'
    errors:
      - code: -32001
        message: Payment failed
        x-fern-audiences:
          - public
        data:
          type: object
          properties:
            error:
              type: string
              const: "Payment could not be processed"
      - code: -32001
        message: Payment failed
        x-fern-audiences:
          - admin
        data:
          type: object
          properties:
            error:
              type: string
            errorCode:
              type: string
            gatewayResponse:
              type: object
            debugTrace:
              type: string

Server-level filtering

Apply audience filtering at the server level:

openrpc.yml

servers:
  - name: public-api
    url: https://api.example.com/rpc
    x-fern-audiences:
      - public
    description: Public API server
  - name: admin-api
    url: https://admin-api.example.com/rpc
    x-fern-audiences:
      - admin
    description: Admin API server with additional privileges

Conditional method availability

Use audiences to make methods available only in certain contexts:

openrpc.yml

methods:
  - name: debug.getSystemInfo
    summary: Get system debug information
    description: Internal system information for debugging
    x-fern-audiences:
      - debug
    params: []
    result:
      name: systemInfo
      schema:
        type: object
        additionalProperties: true
  - name: beta.advancedSearch
    summary: Advanced search functionality
    x-fern-audiences:
      - beta
    params:
      - name: query
        schema:
          type: object
          properties:
            text:
              type: string
            filters:
              type: object
              additionalProperties: true
    result:
      name: results
      schema:
        $ref: '#/components/schemas/SearchResults'
  - name: internal.resetCache
    summary: Reset internal caches
    x-fern-audiences:
      - internal
    params:
      - name: cacheType
        schema:
          type: string
          enum: [user, product, session, all]
    # Notification - no result expected

This allows you to create different views of the same JSON-RPC API for different types of consumers, ensuring each audience only sees the methods and data relevant to their use case.