Amigo Analytics API

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 

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-analytics-api-openapi.yml