Skip to main content
If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the examples property. This property can be added to any response and has the following schema. 
responses:
  "200":
    description: Successful response
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/YourResponseSchema"
        examples:
          us:
            summary: Response for United States
            value:
              countryCode: "US"
              currencyCode: "USD"
              taxRate: 0.0825
          gb:
            summary: Response for United Kingdom
            value:
              countryCode: "GB"
              currencyCode: "GBP"
              taxRate: 0.20

​
Audio response examples

For endpoints that return audio files, you can provide a URL to an audio file in the examples property. The API playground will render an interactive audio player instead of a code snippet. To configure audio response examples:
  1. Set the content type to an audio/* media type (e.g., audio/mpeg, audio/wav, audio/ogg)
  2. Provide a valid URL to an audio file as the example value
responses:
  "200":
    description: Audio file generated successfully
    content:
      audio/mpeg:
        schema:
          type: string
          format: binary
        examples:
          sample:
            summary: Sample audio output
            value: "https://example.com/sample-audio.mp3"
The audio URL will be embedded in an HTML audio player, allowing users to play the example directly in the documentation.