openapi: 3.1.0
info:
  title: Amigo Account Analytics 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: Analytics
paths:
  /v1/{workspace_id}/analytics/usage:
    get:
      tags:
      - Analytics
      summary: Usage Summary
      description: Usage summary grouped by event type and date.
      operationId: usage_summary_v1__workspace_id__analytics_usage_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/calls:
    get:
      tags:
      - Analytics
      summary: Call Stats
      description: Call volume and duration statistics.
      operationId: call_stats_v1__workspace_id__analytics_calls_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/events:
    get:
      tags:
      - Analytics
      summary: Event Breakdown
      description: Event volume breakdown by type and source.
      operationId: event_breakdown_v1__workspace_id__analytics_events_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventBreakdownResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/data-quality:
    get:
      tags:
      - Analytics
      summary: Data Quality Analytics
      description: 'Data quality metrics: confidence distribution, review pipeline stats, daily trends.'
      operationId: data_quality_analytics_v1__workspace_id__analytics_data_quality_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataQualityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/dashboard:
    get:
      tags:
      - Analytics
      summary: Analytics Dashboard
      description: Composite analytics dashboard — top KPIs with period-over-period deltas.
      operationId: get-analytics-dashboard
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          description: Period length in days
          default: 7
          title: Days
        description: Period length in days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsDashboardResponse'
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/eval-quality:
    get:
      tags:
      - Analytics
      summary: Eval Quality Analytics
      description: Production-eval pass-rate and score trends (channel-agnostic — voice, text, SMS, email).
      operationId: get-eval-quality-analytics
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvalQualityResponse'
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/calls/advanced:
    get:
      tags:
      - Analytics
      summary: Advanced Call Stats
      description: 'Percentile-based call metrics: p50/p95/p99 for duration, quality, latency.'
      operationId: get-advanced-call-stats
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      - name: direction
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - inbound
            - outbound
            type: string
          - type: 'null'
          description: 'Filter by call direction: inbound or outbound'
          title: Direction
        description: 'Filter by call direction: inbound or outbound'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Advanced-Call-Stats
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/calls/comparison:
    get:
      tags:
      - Analytics
      summary: Call Comparison
      description: Period-over-period comparison of key call metrics.
      operationId: get-call-comparison
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: current_from
        in: query
        required: true
        schema:
          type: string
          format: date
          description: Start of current period
          title: Current From
        description: Start of current period
      - name: current_to
        in: query
        required: true
        schema:
          type: string
          format: date
          description: End of current period
          title: Current To
        description: End of current period
      - name: previous_from
        in: query
        required: true
        schema:
          type: string
          format: date
          description: Start of previous period
          title: Previous From
        description: Start of previous period
      - name: previous_to
        in: query
        required: true
        schema:
          type: string
          format: date
          description: End of previous period
          title: Previous To
        description: End of previous period
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Call-Comparison
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/call-quality:
    get:
      tags:
      - Analytics
      summary: Call Quality Analytics
      description: Call quality score trends, distribution, and summary statistics.
      operationId: get-call-quality-analytics
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallQualityAnalyticsResponse'
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/emotion-trends:
    get:
      tags:
      - Analytics
      summary: Emotion Trends
      description: Emotion distribution and valence/arousal trends.
      operationId: get-emotion-trends
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Emotion-Trends
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/latency:
    get:
      tags:
      - Analytics
      summary: Latency Analytics
      description: Voice latency metrics — p50/p95/p99 by component with trends.
      operationId: get-latency-analytics
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Latency-Analytics
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/tool-performance:
    get:
      tags:
      - Analytics
      summary: Tool Performance Analytics
      description: Tool execution analytics — success rates, failure trends.
      operationId: get-tool-performance
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Tool-Performance
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/operator-performance:
    get:
      tags:
      - Analytics
      summary: Operator Performance Analytics
      description: Operator escalation stats and quality comparison.
      operationId: get-operator-performance
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorPerformanceResponse'
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/agents:
    get:
      tags:
      - Analytics
      summary: Get Agent Analytics
      description: Per-agent (service) call volume, completion rate, and avg duration.
      operationId: get-agent-analytics
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: period
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Period
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAnalyticsResponse'
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/surfaces/completion-rates:
    get:
      tags:
      - Analytics
      summary: Surface Completion Rates
      description: 'Surface completion rates: overall, by source, time-bucketed trend.'
      operationId: get-surface-completion-rates
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: interval
        in: query
        required: false
        schema:
          enum:
          - 1h
          - 1d
          - 1w
          type: string
          default: 1d
          title: Interval
      - name: entity_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by entity ID
          title: Entity Id
        description: Filter by entity ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Surface-Completion-Rates
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/surfaces/channel-effectiveness:
    get:
      tags:
      - Analytics
      summary: Surface Channel Effectiveness
      description: Per-channel completion rate and average time to complete.
      operationId: get-surface-channel-effectiveness
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Surface-Channel-Effectiveness
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/surfaces/field-abandonment:
    get:
      tags:
      - Analytics
      summary: Surface Field Abandonment
      description: Field-level drop-off analysis for abandoned surfaces.
      operationId: get-surface-field-abandonment
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Surface-Field-Abandonment
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/analytics/surfaces/entity/{entity_id}:
    get:
      tags:
      - Analytics
      summary: Entity Surface History
      description: Per-entity surface history with preferred channel and completion stats.
      operationId: get-entity-surface-history
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Entity Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Entity-Surface-History
        '429':
          description: Rate limit exceeded
        '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
    DailyCallStat:
      properties:
        date:
          type: string
          title: Date
          description: Date string (YYYY-MM-DD)
        count:
          type: integer
          title: Count
          description: Number of calls on this date
        avg_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Duration Seconds
          description: Average call duration in seconds
      type: object
      required:
      - date
      - count
      title: DailyCallStat
      description: Per-day call volume and duration.
    OperatorPerformanceTrendPoint:
      properties:
        date:
          type: string
          format: date
          title: Date
          description: Date for the time bucket
        total_calls:
          type: integer
          title: Total Calls
          description: Total calls in this time bucket
        escalated_count:
          type: integer
          title: Escalated Count
          description: Escalated calls in this time bucket
      type: object
      required:
      - date
      - total_calls
      - escalated_count
      title: OperatorPerformanceTrendPoint
      description: Single time-bucket data point in the operator performance trend series.
    ConfidenceBucket:
      properties:
        confidence_range:
          type: string
          title: Confidence Range
          description: Confidence level bucket label (e.g. 'raw', 'verified', 'authoritative')
        count:
          type: integer
          title: Count
          description: Number of events in this confidence bucket
      type: object
      required:
      - confidence_range
      - count
      title: ConfidenceBucket
    OperatorPerformanceResponse:
      properties:
        summary:
          $ref: '#/components/schemas/OperatorPerformanceSummary'
          description: Aggregate operator performance metrics
        trend:
          items:
            $ref: '#/components/schemas/OperatorPerformanceTrendPoint'
          type: array
          maxItems: 2200
          title: Trend
          description: Time series of escalation counts per interval bucket
      type: object
      required:
      - summary
      - trend
      title: OperatorPerformanceResponse
      description: Operator escalation performance and quality comparison over time.
    EventBreakdownResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
          description: Workspace identifier
        period_start:
          type: string
          format: date
          title: Period Start
          description: Start of the reporting period
        period_end:
          type: string
          format: date
          title: Period End
          description: End of the reporting period
        by_type:
          items:
            $ref: '#/components/schemas/EventBreakdownItem'
          type: array
          title: By Type
          description: Event counts grouped by event type
        by_source:
          items:
            $ref: '#/components/schemas/EventBreakdownItem'
          type: array
          title: By Source
          description: Event counts grouped by source
        total_events:
          type: integer
          title: Total Events
          description: Total number of events in the period
      type: object
      required:
      - workspace_id
      - period_start
      - period_end
      - by_type
      - by_source
      - total_events
      title: EventBreakdownResponse
    EvalQualityResponse:
      properties:
        summary:
          $ref: '#/components/schemas/EvalQualitySummary'
          description: Workspace-wide aggregate for the period
        by_eval_key:
          items:
            $ref: '#/components/schemas/EvalQualitySummary'
          type: array
          maxItems: 200
          title: By Eval Key
          description: Per-eval-key aggregates, most-evaluated first
        trend:
          items:
            $ref: '#/components/schemas/EvalQualityTrendPoint'
          type: array
          maxItems: 2200
          title: Trend
          description: Time series of eval pass-rate/score per interval bucket
      type: object
      required:
      - summary
      - by_eval_key
      - trend
      title: EvalQualityResponse
      description: 'Production-eval quality: overall pass-rate/score, per-eval-key breakdown, and a trend.


        The channel-agnostic quality surface. Returns zeroed shapes (empty ``by_eval_key``

        and ``trend``, null rates) when no verdicts exist for the workspace/window — the

        console renders an empty-state rather than erroring, so this ships safely ahead of

        the eager-eval trigger being enabled in production.'
    CallQualityDistribution:
      properties:
        excellent_90_100:
          type: integer
          title: Excellent 90 100
          description: Calls with quality score 90-100
        good_70_89:
          type: integer
          title: Good 70 89
          description: Calls with quality score 70-89
        fair_50_69:
          type: integer
          title: Fair 50 69
          description: Calls with quality score 50-69
        poor_0_49:
          type: integer
          title: Poor 0 49
          description: Calls with quality score 0-49
      type: object
      required:
      - excellent_90_100
      - good_70_89
      - fair_50_69
      - poor_0_49
      title: CallQualityDistribution
      description: Call counts bucketed by quality-score band.
    AgentAnalyticsEntry:
      properties:
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        agent_name:
          type: string
          title: Agent Name
        total_calls:
          type: integer
          title: Total Calls
        completed_calls:
          type: integer
          title: Completed Calls
        avg_duration_seconds:
          type: number
          title: Avg Duration Seconds
        completion_rate:
          type: number
          title: Completion Rate
      type: object
      required:
      - agent_id
      - agent_name
      - total_calls
      - completed_calls
      - avg_duration_seconds
      - completion_rate
      title: AgentAnalyticsEntry
    CallStatsResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
          description: Workspace identifier
        period_start:
          type: string
          format: date
          title: Period Start
          description: Start of the reporting period
        period_end:
          type: string
          format: date
          title: Period End
          description: End of the reporting period
        total_calls:
          type: integer
          title: Total Calls
          description: Total number of calls in the period
        total_duration_seconds:
          type: number
          title: Total Duration Seconds
          description: Sum of all call durations in seconds
        avg_duration_seconds:
          type: number
          title: Avg Duration Seconds
          description: Average call duration in seconds
        calls_by_date:
          items:
            $ref: '#/components/schemas/DailyCallStat'
          type: array
          title: Calls By Date
          description: Daily call volume breakdown
      type: object
      required:
      - workspace_id
      - period_start
      - period_end
      - total_calls
      - total_duration_seconds
      - avg_duration_seconds
      - calls_by_date
      title: CallStatsResponse
    DataQualityResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
          description: Workspace identifier
        period_start:
          type: string
          format: date
          title: Period Start
          description: Start of the reporting period
        period_end:
          type: string
          format: date
          title: Period End
          description: End of the reporting period
        confidence_distribution:
          items:
            $ref: '#/components/schemas/ConfidenceBucket'
          type: array
          title: Confidence Distribution
          description: Overall confidence distribution across buckets
        confidence_by_source:
          additionalProperties:
            items:
              $ref: '#/components/schemas/ConfidenceBucket'
            type: array
          type: object
          title: Confidence By Source
          description: Confidence distribution broken down by event source
        review_pipeline:
          additionalProperties: true
          type: object
          title: Review Pipeline
          description: Review pipeline throughput statistics
        timeseries:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Timeseries
          description: Daily confidence averages and event counts
        total_events:
          type: integer
          title: Total Events
          description: Total number of events in the period
      type: object
      required:
      - workspace_id
      - period_start
      - period_end
      - confidence_distribution
      - confidence_by_source
      - review_pipeline
      - timeseries
      - total_events
      title: DataQualityResponse
      description: Data quality metrics — confidence distribution, review pipeline stats.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EvalQualityTrendPoint:
      properties:
        date:
          type: string
          format: date
          title: Date
          description: Date bucket (granularity follows `interval`)
        total_evals:
          type: integer
          title: Total Evals
          description: Total verdicts in this bucket
        judged:
          type: integer
          title: Judged
          description: Verdicts with a non-null pass/fail outcome in this bucket
        pass_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Pass Rate
          description: Fraction of judged verdicts that passed in this bucket
        avg_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Score
          description: Mean numeric judge score in this bucket
      type: object
      required:
      - date
      - total_evals
      - judged
      title: EvalQualityTrendPoint
      description: Single date-bucket data point in the eval-quality trend series.
    CallQualityTrendPoint:
      properties:
        date:
          type: string
          title: Date
          description: Time bucket as an ISO-8601 timestamp string (granularity follows `interval`)
        avg_quality:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Quality
          description: Average quality score in this bucket (0-100)
        call_count:
          type: integer
          title: Call Count
          description: Number of calls in this bucket
        escalation_count:
          type: integer
          title: Escalation Count
          description: Number of escalated calls in this bucket
      type: object
      required:
      - date
      - call_count
      - escalation_count
      title: CallQualityTrendPoint
      description: Single time-bucket data point in the call-quality trend series.
    CallQualityAnalyticsResponse:
      properties:
        summary:
          $ref: '#/components/schemas/CallQualitySummary'
          description: Aggregate call-quality metrics for the period
        trend:
          items:
            $ref: '#/components/schemas/CallQualityTrendPoint'
          type: array
          maxItems: 2200
          title: Trend
          description: Time series of call-quality metrics per interval bucket
        quality_distribution:
          $ref: '#/components/schemas/CallQualityDistribution'
          description: Call counts bucketed by quality-score band
      type: object
      required:
      - summary
      - trend
      - quality_distribution
      title: CallQualityAnalyticsResponse
      description: 'Call quality score trends, distribution, and summary over time.


        Served from the live Delta projection ``analytics.source_call_intelligence``.'
    UsageSummaryResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
          description: Workspace identifier
        period_start:
          type: string
          format: date
          title: Period Start
          description: Start of the reporting period
        period_end:
          type: string
          format: date
          title: Period End
          description: End of the reporting period
        buckets:
          items:
            $ref: '#/components/schemas/UsageBucket'
          type: array
          title: Buckets
          description: Usage data grouped by event type and date
        total_events:
          type: integer
          title: Total Events
          description: Total number of events in the period
      type: object
      required:
      - workspace_id
      - period_start
      - period_end
      - buckets
      - total_events
      title: UsageSummaryResponse
    UsageBucket:
      properties:
        event_type:
          type: string
          title: Event Type
          description: World event type
        event_date:
          type: string
          format: date
          title: Event Date
          description: Date of the usage bucket
        count:
          type: integer
          title: Count
          description: Number of events in this bucket
        avg_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Duration Seconds
          description: Average event duration in seconds
        total_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Duration Seconds
          description: Total event duration in seconds
      type: object
      required:
      - event_type
      - event_date
      - count
      title: UsageBucket
    AnalyticsDashboardResponse:
      properties:
        call_volume:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Total calls in the period
        avg_quality:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Average quality score (0-100); higher is better
        avg_ttfb_ms:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Average audio time-to-first-byte in ms; lower is better
        escalation_rate:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Fraction of calls escalated; lower is better
        tool_success_rate:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Fraction of tool calls that succeeded; higher is better
        avg_duration_s:
          $ref: '#/components/schemas/AnalyticsKpi'
          description: Average call duration in seconds
        period_days:
          type: integer
          title: Period Days
          description: Length of the reporting period in days
      type: object
      required:
      - call_volume
      - avg_quality
      - avg_ttfb_ms
      - escalation_rate
      - tool_success_rate
      - avg_duration_s
      - period_days
      title: AnalyticsDashboardResponse
      description: 'Composite dashboard — six headline KPIs, each with a delta, plus the period length.


        Higher-is-better for ``call_volume``, ``avg_quality``, ``tool_success_rate``;

        higher-is-worse for ``escalation_rate``, ``avg_ttfb_ms``, ``avg_duration_s``.

        Consumers must color deltas by that per-KPI polarity, not by delta sign alone.'
    CallQualitySummary:
      properties:
        avg_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Quality Score
          description: Mean quality score across calls (0-100)
        p50_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: P50 Quality Score
          description: Median quality score (0-100)
        p95_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: P95 Quality Score
          description: 95th-percentile quality score (0-100)
        total_calls:
          type: integer
          title: Total Calls
          description: Total number of calls in the period
        escalation_rate:
          type: number
          title: Escalation Rate
          description: Fraction of calls escalated to an operator (0.0-1.0)
        avg_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Duration Seconds
          description: Average call duration in seconds
      type: object
      required:
      - total_calls
      - escalation_rate
      title: CallQualitySummary
      description: Aggregate call-quality stats for the period.
    EvalQualitySummary:
      properties:
        eval_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Eval Key
          description: Eval key for a per-key row; null for the overall summary
        total_evals:
          type: integer
          title: Total Evals
          description: Total verdicts recorded (any status, incl. errored)
        judged:
          type: integer
          title: Judged
          description: Verdicts with a non-null pass/fail outcome (denominator for pass_rate)
        pass_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Pass Rate
          description: Fraction of judged verdicts that passed (0.0-1.0)
        avg_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Score
          description: Mean numeric judge score across scored verdicts
      type: object
      required:
      - total_evals
      - judged
      title: EvalQualitySummary
      description: 'Aggregate production-eval verdict stats, overall or for one eval_key.


        Sourced from ``call_eval_results`` (LLM-judge + assertion verdicts), which is

        keyed by ``conversation_id`` and therefore CHANNEL-AGNOSTIC — voice, text,

        SMS, email all contribute equally, unlike the voice-shaped call-quality score.'
    AgentAnalyticsResponse:
      properties:
        agents:
          items:
            $ref: '#/components/schemas/AgentAnalyticsEntry'
          type: array
          title: Agents
        period:
          anyOf:
          - type: string
          - type: 'null'
          title: Period
      type: object
      required:
      - agents
      title: AgentAnalyticsResponse
    OperatorPerformanceSummary:
      properties:
        total_calls:
          type: integer
          title: Total Calls
          description: Total number of calls in the period
        escalated_count:
          type: integer
          title: Escalated Count
          description: Number of calls escalated to an operator
        escalation_rate:
          type: number
          title: Escalation Rate
          description: Fraction of calls that were escalated (0.0-1.0)
        operator_handled_count:
          type: integer
          title: Operator Handled Count
          description: Number of calls where an operator was active
        avg_escalated_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Escalated Duration Seconds
          description: Average duration in seconds of escalated calls
        avg_escalated_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Escalated Quality Score
          description: Average quality score of escalated calls
        avg_non_escalated_quality_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Non Escalated Quality Score
          description: Average quality score of non-escalated calls
      type: object
      required:
      - total_calls
      - escalated_count
      - escalation_rate
      - operator_handled_count
      title: OperatorPerformanceSummary
      description: Aggregate operator escalation stats for the period.
    EventBreakdownItem:
      properties:
        key:
          type: string
          title: Key
          description: Grouping key (event type or source name)
        count:
          type: integer
          title: Count
          description: Number of events for this key
      type: object
      required:
      - key
      - count
      title: EventBreakdownItem
      description: Single row in an event breakdown aggregation.
    AnalyticsKpi:
      properties:
        value:
          anyOf:
          - type: number
          - type: 'null'
          title: Value
          description: Current-period value (None when no data)
        delta_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Delta Pct
          description: Percent change vs the previous period, or None
      type: object
      title: AnalyticsKpi
      description: 'A single headline KPI with its period-over-period change.


        ``value`` is left broad (int for counts, float for rates/scores/durations,

        ``None`` when the metric has no data for the period). ``delta_pct`` is the

        signed percent change vs the previous equal-length period, or ``None`` when

        a prior-period comparison is unavailable.'
  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.