openapi: 3.1.0
info:
  title: Amigo Account Voice Judge API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: Voice Judge
paths:
  /v1/{workspace_id}/services/{service_id}/voice-judge/recent:
    get:
      tags:
      - Voice Judge
      summary: Recent voice-judge results for a service
      description: 'Returns the most recent per-call voice-judge scores for one service, ordered newest first. Produced by the Databricks `voice_judge` job (stereo audio → Gemini 2.5 Flash → 10-dimension rubric). Used by the Agent Readiness page to populate Voice Quality criterion cards.


        **Latency**: 500ms-2s (reads from analytics warehouse, not OLTP).


        **Default limit**: 20. Max 100.'
      operationId: list-voice-judge-recent
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Service Id
          description: Service UUID
        description: Service UUID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max rows to return (default 20, max 100)
          default: 20
          title: Limit
        description: Max rows to return (default 20, max 100)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Offset for pagination (default 0)
          default: 0
          title: Offset
        description: Offset for pagination (default 0)
      responses:
        '200':
          description: Voice judge rows (newest first)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceJudgeRecentResponse'
        '503':
          description: Analytics warehouse not configured or transiently unavailable
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VoiceJudgeResultRow:
      properties:
        call_sid:
          type: string
          maxLength: 64
          title: Call Sid
        call_entity_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Call Entity Id
        service_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Id
        latency_dead_air_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Latency Dead Air Score
        pronunciation_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Pronunciation Score
        clarity_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Clarity Score
        filler_silence_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Filler Silence Score
        interruption_handling_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Interruption Handling Score
        audio_consistency_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Audio Consistency Score
        pacing_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Pacing Score
        warmth_tone_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Warmth Tone Score
        accent_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Accent Quality Score
        voice_identity_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Voice Identity Score
        overall_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Overall Score
        critical_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Critical Count
        flag_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Flag Count
        warning_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Warning Count
        judge_json:
          anyOf:
          - type: string
            maxLength: 32768
          - type: 'null'
          title: Judge Json
          description: Raw Gemini judge output (evidence quotes, per-dim severity). Intended for UI drill-in; opaque string. Capped at 32KB.
        computed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Computed At
      type: object
      required:
      - call_sid
      title: VoiceJudgeResultRow
      description: One call's voice-judge scoring, as stored in the Delta output table.
    VoiceJudgeRecentResponse:
      properties:
        service_id:
          type: string
          format: uuid
          title: Service Id
        count:
          type: integer
          minimum: 0.0
          title: Count
        items:
          items:
            $ref: '#/components/schemas/VoiceJudgeResultRow'
          type: array
          title: Items
      type: object
      required:
      - service_id
      - count
      - items
      title: VoiceJudgeRecentResponse
  securitySchemes:
    Bearer-Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint.
    Bearer-Authorization-Organization:
      type: apiKey
      in: header
      name: X-ORG-ID
      description: An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
    Basic:
      type: http
      scheme: basic
      description: The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.