openapi: 3.2.0
info:
  title: Reference Recordings API
  version: 1.0.0
servers:
- url: https://api.virtuosis.ai/v1.3
  description: https://api.virtuosis.ai/v1.3
tags:
- name: recordings
paths:
  /recordings:
    post:
      operationId: uploadRecording
      summary: Upload a recording for analysis
      description: 'Uploads a Base64-encoded audio file. Analysis processing is triggered on a successful

        upload and may take up to five minutes to complete. Requires an active

        subscription with available credits; requests are rejected once the balance is

        exhausted or the subscription is suspended.


        Minimum audio requirements:

        - Format: WAV, MP3, MP4, or OGG

        - Sample rate: 8,000 Hz

        - Bit rate: 32,000 bps

        - Channels: 1 (mono)

        - Duration: 30 seconds of speech

        - Maximum file size: 50 MB

        '
      tags:
      - recordings
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Recording uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadRecordingResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Requested analysis is not enabled, access is suspended, or API billing is not provisioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: File too large (max 50 MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRecordingRequest'
  /recordings/{recording_id}/analysis:
    get:
      operationId: getRecordingAnalysis
      summary: Get analysis results for a recording
      description: 'Poll for analysis results after uploading a recording. To avoid rate limiting, a polling interval of 15-30 seconds is recommended (minimum 5 seconds), with a polling timeout of five minutes.

        '
      tags:
      - recordings
      parameters:
      - name: recording_id
        in: path
        description: The ID of the recording.
        required: true
        schema:
          type: string
          format: uuid
      - name: analysis
        in: query
        description: 'Comma-separated list of analysis types to include (default: all)'
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingAnalysisResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access is suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AnxietyInsightRating:
      type: string
      enum:
      - minimal
      - mild
      - moderate
      - severe
      description: Predicted anxiety level.
      title: AnxietyInsightRating
    StressInsightRating:
      type: string
      enum:
      - low
      - moderate
      - high
      description: Predicted stress level.
      title: StressInsightRating
    AnxietyInsight:
      type: object
      properties:
        rating:
          $ref: '#/components/schemas/AnxietyInsightRating'
          description: Predicted anxiety level.
      required:
      - rating
      title: AnxietyInsight
    UploadRecordingRequest:
      type: object
      properties:
        account_id:
          type: string
          format: uuid
          description: The ID of the account submitting the recording.
        recorded_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the recording began.
        analysis:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisType'
          description: Analysis types to run. Must contain at least one type.
        audio:
          type: string
          description: Base64-encoded audio file.
        isolate_oldest_speaker:
          type: boolean
          default: false
          description: 'When true, the clip is diarised and only the audio of the speaker estimated to be oldest is kept and analysed. Speaker age is estimated from the audio and carries a multi-year error bar, so speakers close in age may not be separated reliably. The retained speaker''s speech must clear the same 30-second minimum the whole clip does, or the upload is rejected with a SpeakerSpeechTooShort error. Recordings longer than 10 minutes are rejected with a RecordingTooLongForIsolation error.

            '
      required:
      - account_id
      - recorded_at
      - analysis
      - audio
      title: UploadRecordingRequest
    CommunicationCoachInsights:
      type: object
      properties:
        rhythm:
          $ref: '#/components/schemas/CommunicationCoachInsight'
          description: Score reflecting the balance between speech and pauses.
        clarity:
          $ref: '#/components/schemas/CommunicationCoachInsight'
          description: Score reflecting the proportion of intelligible speech.
        positiveness:
          $ref: '#/components/schemas/CommunicationCoachInsight'
          description: Score reflecting the proportion of speech with a positive tone.
        speaking_rate:
          $ref: '#/components/schemas/CommunicationCoachInsight'
          description: Score reflecting how closely the speaker's word rate matches the ideal words-per-minute rate.
      required:
      - rhythm
      - clarity
      - positiveness
      - speaking_rate
      description: Communication coach insights keyed by aspect. Present only when analysis completed.
      title: CommunicationCoachInsights
    ParkinsonsIndicators:
      type: object
      properties:
        volume:
          type: integer
          description: Mean energy in decibels.
        monoloudness:
          type: number
          format: double
          description: Standard deviation of loudness across the utterance in decibels.
        monotony:
          type: integer
          description: Standard deviation of the fundamental frequency in hertz.
        articulation:
          type: integer
          description: Dynamic range of the second formant in hertz.
        speech_rate:
          type: integer
          description: Mean number of words spoken per minute.
        speech_rate_stdev:
          type: integer
          description: Standard deviation of speech rate in words-per-minute.
        pause_duration:
          type: integer
          description: Mean duration of silent pauses in milliseconds.
        pause_duration_stdev:
          type: integer
          description: Standard deviation of pause duration in milliseconds.
        voice_quality:
          type: number
          format: double
          description: Cepstral peak prominence in decibels.
        hnr:
          type: integer
          description: Harmonics-to-noise ratio in decibels.
        stuttering:
          type: number
          format: double
          description: Word and n-gram repetitions per minute.
      description: 'Acoustic and speech indicators used for Parkinson''s analysis. Omitted if analysis did not complete; individual indicators are omitted when unavailable.

        '
      title: ParkinsonsIndicators
    CommunicationCoachAnalysis:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnalysisStatus'
          description: Status of communication coach analysis processing.
        indicators:
          $ref: '#/components/schemas/CommunicationCoachIndicators'
          description: Communication-related speech indicators.
        insights:
          $ref: '#/components/schemas/CommunicationCoachInsights'
          description: Communication coach scores.
      required:
      - status
      title: CommunicationCoachAnalysis
    RecordingAnalysis:
      type: object
      properties:
        wellbeing:
          $ref: '#/components/schemas/WellbeingAnalysis'
          description: Wellbeing analysis results.
        parkinsons:
          $ref: '#/components/schemas/ParkinsonsAnalysis'
          description: Parkinson's analysis results.
        alzheimers:
          $ref: '#/components/schemas/AlzheimersAnalysis'
          description: Alzheimer's analysis results.
        communication_coach:
          $ref: '#/components/schemas/CommunicationCoachAnalysis'
          description: Communication coach analysis results.
      description: Analysis results grouped by type.
      title: RecordingAnalysis
    AlzheimersAnalysis:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnalysisStatus'
          description: Status of Alzheimer's analysis processing.
        indicators:
          $ref: '#/components/schemas/AlzheimersIndicators'
          description: Alzheimer's-related linguistic indicators.
        insights:
          $ref: '#/components/schemas/AlzheimersInsights'
          description: Cognition insights keyed by condition.
      required:
      - status
      title: AlzheimersAnalysis
    WellbeingInsights:
      type: object
      properties:
        stress:
          $ref: '#/components/schemas/StressInsight'
          description: Stress insight.
        anxiety:
          $ref: '#/components/schemas/AnxietyInsight'
          description: Anxiety insight.
        depression:
          $ref: '#/components/schemas/DepressionInsight'
          description: Depression insight.
      title: WellbeingInsights
    AlzheimersIndicators:
      type: object
      properties:
        ttr:
          type: number
          format: double
          description: Type-token ratio.
        brunet_index:
          type: number
          format: double
          description: Brunet's index.
        content_ratio:
          type: number
          format: double
          description: Ratio of content words to total words.
        mlu_words:
          type: number
          format: double
          description: Mean length of utterance in words.
        clause_ratio:
          type: number
          format: double
          description: Ratio of clauses to utterances.
        speech_rate:
          type: number
          format: double
          description: Mean number of words spoken per minute.
        speech_rate_stdev:
          type: number
          format: double
          description: Standard deviation of speech rate in words-per-minute.
        avg_pause_duration_ms:
          type: number
          format: double
          description: Mean pause duration in milliseconds.
        pause_filler_words_per_min:
          type: number
          format: double
          description: Pause filler words per minute.
        long_pause_ratio:
          type: number
          format: double
          description: Proportion of total audio duration spent in long pauses.
      description: 'Linguistic and speech indicators used for Alzheimer''s analysis. Omitted if analysis did not complete; individual indicators are omitted when unavailable.

        '
      title: AlzheimersIndicators
    UploadRecordingResponse:
      type: object
      properties:
        recording_id:
          type: string
          format: uuid
          description: The recording ID used for fetching analysis results.
        account_id:
          type: string
          format: uuid
          description: The ID of the account that submitted the recording.
        recorded_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the recording began.
        uploaded_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the recording was uploaded.
        audio_file_format:
          type: string
          description: Detected audio file format.
        audio_size_bytes:
          type: integer
          description: 'Audio file size in bytes. With isolate_oldest_speaker enabled, this describes the retained audio, not the submitted file.

            '
        audio_sample_rate_hz:
          type: integer
          description: Audio sample rate in Hz.
        audio_bit_rate_bps:
          type: integer
          description: Audio bit rate in bits per second.
        audio_duration_seconds:
          type: number
          format: double
          description: 'Total audio duration in seconds. With isolate_oldest_speaker enabled, this is the duration of the retained speaker''s audio, not of the submitted clip.

            '
        speech_duration_seconds:
          type: number
          format: double
          description: 'Detected speech duration in seconds. With isolate_oldest_speaker enabled, this is the isolated speaker''s speech time, not the whole clip''s.

            '
      required:
      - recording_id
      - account_id
      - recorded_at
      - uploaded_at
      - audio_file_format
      - audio_size_bytes
      - audio_sample_rate_hz
      - audio_bit_rate_bps
      - audio_duration_seconds
      - speech_duration_seconds
      title: UploadRecordingResponse
    WellbeingAnalysis:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnalysisStatus'
          description: Status of wellbeing analysis processing.
        insights:
          $ref: '#/components/schemas/WellbeingInsights'
          description: Wellbeing insights keyed by condition.
      required:
      - status
      title: WellbeingAnalysis
    DepressionInsight:
      type: object
      properties:
        rating:
          $ref: '#/components/schemas/DepressionInsightRating'
          description: Predicted depression level.
      required:
      - rating
      title: DepressionInsight
    ParkinsonsInsights:
      type: object
      properties:
        parkinsons:
          $ref: '#/components/schemas/ParkinsonsInsight'
          description: Parkinson's risk insight.
      title: ParkinsonsInsights
    CognitionScores:
      type: object
      properties:
        hc:
          type: number
          format: double
          description: Probability of healthy.
        mci:
          type: number
          format: double
          description: Probability of mild cognitive impairment.
        ad:
          type: number
          format: double
          description: Probability of Alzheimer's disease.
      description: Class probability distribution. Individual probabilities are omitted when unavailable.
      title: CognitionScores
    ParkinsonsAnalysis:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnalysisStatus'
          description: Status of Parkinson's analysis processing.
        indicators:
          $ref: '#/components/schemas/ParkinsonsIndicators'
          description: Parkinson's-related acoustic indicators.
        insights:
          $ref: '#/components/schemas/ParkinsonsInsights'
          description: Parkinson's insights keyed by condition.
      required:
      - status
      title: ParkinsonsAnalysis
    DepressionInsightRating:
      type: string
      enum:
      - minimal
      - moderate
      - severe
      description: Predicted depression level.
      title: DepressionInsightRating
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorError'
          description: Error details.
      required:
      - error
      title: Error
    AnalysisType:
      type: string
      enum:
      - wellbeing
      - parkinsons
      - alzheimers
      - communication_coach
      description: Analysis type identifier.
      title: AnalysisType
    ParkinsonsInsight:
      type: object
      properties:
        rating:
          type: string
          description: Parkinson's risk band derived from the risk score.
        score:
          type: integer
          description: Parkinson's disease probability.
      description: 'Parkinson''s risk insight. Omitted if analysis did not complete; rating and score are omitted when unavailable.

        '
      title: ParkinsonsInsight
    RecordingAnalysisResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/RecordingAnalysisMetadata'
          description: Metadata about the recording.
        analysis:
          $ref: '#/components/schemas/RecordingAnalysis'
          description: Analysis results grouped by type.
      required:
      - metadata
      - analysis
      title: RecordingAnalysisResponse
    AnalysisStatus:
      type: string
      enum:
      - completed
      - processing
      - error
      - not_requested
      description: Status of analysis processing.
      title: AnalysisStatus
    StressInsight:
      type: object
      properties:
        rating:
          $ref: '#/components/schemas/StressInsightRating'
          description: Predicted stress level.
      required:
      - rating
      title: StressInsight
    ErrorError:
      type: object
      properties:
        type:
          type: string
          description: Machine-readable error type.
        message:
          type: string
          description: Human-readable description of the error.
      required:
      - type
      - message
      description: Error details.
      title: ErrorError
    CognitionInsight:
      type: object
      properties:
        rating:
          type: string
          description: Predicted classification (hc, mci, or ad).
        scores:
          $ref: '#/components/schemas/CognitionScores'
          description: Class probability distribution.
      description: 'Cognition insight. Omitted if analysis did not complete; rating and scores are omitted when unavailable.

        '
      title: CognitionInsight
    AlzheimersInsights:
      type: object
      properties:
        cognition:
          $ref: '#/components/schemas/CognitionInsight'
          description: Cognition insight.
      title: AlzheimersInsights
    CommunicationCoachInsight:
      type: object
      properties:
        score:
          type: integer
          description: Score from 0 to 100.
      required:
      - score
      description: Overall communication score
      title: CommunicationCoachInsight
    RecordingAnalysisMetadata:
      type: object
      properties:
        recording_id:
          type: string
          format: uuid
          description: The ID of the recording.
        account_id:
          type: string
          format: uuid
          description: The ID of the account that submitted the recording.
        recorded_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the recording began.
        uploaded_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the recording was uploaded. Omitted when unavailable.
        audio_file_format:
          type: string
          description: Detected audio file format. Omitted when unavailable.
        audio_size_bytes:
          type: integer
          description: Audio file size in bytes. Omitted when unavailable.
        audio_duration_seconds:
          type: number
          format: double
          description: Total audio duration in seconds.
        audio_sample_rate_hz:
          type: integer
          description: Audio sample rate in Hz. Omitted when unavailable.
        audio_bit_rate_bps:
          type: integer
          description: Audio bit rate in bits per second. Omitted when unavailable.
        speech_duration_seconds:
          type: number
          format: double
          description: Detected speech duration in seconds. Omitted when unavailable.
      required:
      - recording_id
      - account_id
      - recorded_at
      - audio_duration_seconds
      description: Metadata about the recording.
      title: RecordingAnalysisMetadata
    CommunicationCoachIndicators:
      type: object
      properties:
        word_rate:
          type: integer
          description: Words spoken per minute.
        fragment_rate:
          type: integer
          description: Speech fragments per minute.
        filler_words_rate:
          type: number
          format: double
          description: Filler words per minute.
      required:
      - word_rate
      - fragment_rate
      - filler_words_rate
      description: Speech quantities measured from the audio. Present only when analysis completed.
      title: CommunicationCoachIndicators
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer