Amigo Operators API

openapi: 3.1.0
info:
  title: Amigo Account Operators 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: Operators
paths:
  /v1/{workspace_id}/operators/dashboard:
    get:
      tags:
      - Operators
      summary: Operator dashboard overview
      description: Live dashboard with operator status counts, active escalation queue, and today's escalation statistics.
      operationId: operator-dashboard
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardResponse'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/operators/performance:
    get:
      tags:
      - Operators
      summary: Operator performance summary
      description: Aggregate performance across all operators with per-operator breakdown.
      operationId: operator-performance-summary
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceSummaryResponse'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/operators/escalations/active:
    get:
      tags:
      - Operators
      summary: List active escalations
      description: 'List calls with active escalations (status: requested or connected).'
      operationId: list-active-escalations
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          default: 10
          title: Limit
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Continuation Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_ActiveEscalationItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/escalations/stats:
    get:
      tags:
      - Operators
      summary: Escalation statistics
      description: Aggregated escalation statistics over a time period.
      operationId: escalation-stats
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: period
        in: query
        required: false
        schema:
          enum:
          - day
          - week
          - month
          type: string
          description: 'Time period: day, week, or month.'
          default: day
          title: Period
        description: 'Time period: day, week, or month.'
      - name: group_by
        in: query
        required: false
        schema:
          enum:
          - status
          - trigger
          - operator
          type: string
          description: 'Grouping dimension: status, trigger, or operator.'
          default: status
          title: Group By
        description: 'Grouping dimension: status, trigger, or operator.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/escalations:
    get:
      tags:
      - Operators
      summary: List escalation events
      description: List escalation lifecycle events for a workspace.
      operationId: list-escalations
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          default: 10
          title: Limit
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Continuation Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_EscalationEventResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/audit-log:
    get:
      tags:
      - Operators
      summary: Query audit log
      description: Query audit events (operator actions) for a workspace.
      operationId: list-audit-log
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by operator entity UUID.
          title: Operator Id
        description: Filter by operator entity UUID.
      - name: action
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - operator.registered
            - operator.status_changed
            - operator.profile_updated
            - operator.joined_call
            - operator.mode_changed
            - operator.mode_switched
            - operator.left_call
            - operator.access_token_generated
            - operator.guidance_sent
            - operator.wrap_up
            - operator.viewed_transcript
            type: string
          - type: 'null'
          description: Filter by exact operator audit event type.
          title: Action
        description: Filter by exact operator audit event type.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          default: 10
          title: Limit
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Continuation Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_AuditEventResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/calls/{call_sid}/transcript:
    get:
      tags:
      - Operators
      summary: Get call transcript
      description: Per-speaker transcript segments from operator takeover sessions.
      operationId: get-call-transcript
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_sid
        in: path
        required: true
        schema:
          type: string
          title: Call Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTranscriptResponse'
        '404':
          description: Call not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/queue:
    get:
      tags:
      - Operators
      summary: Priority-ranked operator queue
      description: 'Active calls ranked by operator priority: risk, wait time, emotion, loops, and safety concerns.'
      operationId: get-operator-queue
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriorityQueueResponse'
        '429':
          description: Rate limit exceeded.
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/operators/{operator_id}/briefing:
    post:
      tags:
      - Operators
      summary: Generate operator briefing
      description: Structured briefing for an operator about to join a call. Template-rendered from call intelligence and entity context.
      operationId: create-operator-briefing
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BriefingRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BriefingResponse'
        '400':
          description: Invalid operator_id.
        '429':
          description: Rate limit exceeded.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/join-call:
    post:
      tags:
      - Operators
      summary: Join active call as operator
      description: Add operator to an active call's Twilio Conference.
      operationId: operator-join-call
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JoinCallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinCallResponse'
        '404':
          description: Operator or active call not found.
        '409':
          description: Operator is already on a call.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/leave-call:
    post:
      tags:
      - Operators
      summary: Remove operator from active call
      description: Remove operator from an active call's Twilio Conference.
      operationId: operator-leave-call
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaveCallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaveCallResponse'
        '404':
          description: Operator or active call not found.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/access-token:
    post:
      tags:
      - Operators
      summary: Generate browser audio access token
      description: Generate a Twilio AccessToken with VoiceGrant for browser-based operator audio.
      operationId: operator-access-token
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        '404':
          description: Operator or active call not found.
        '503':
          description: Browser audio not configured or voice agent unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/switch-mode:
    post:
      tags:
      - Operators
      summary: Toggle operator listen/takeover mode
      description: Switch between listen mode and takeover mode.
      operationId: operator-switch-mode
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchModeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwitchModeResponse'
        '404':
          description: Operator not found.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/send-guidance:
    post:
      tags:
      - Operators
      summary: Send text guidance to agent during call
      description: Inject operator guidance into an active call. The agent incorporates it into its next response.
      operationId: operator-send-guidance
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendGuidanceRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendGuidanceResponse'
        '404':
          description: Operator or active call not found.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}/wrap-up:
    post:
      tags:
      - Operators
      summary: Record operator intervention wrap-up
      description: Persist the outcome and notes from an operator's call intervention.
      operationId: operator-wrap-up
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WrapUpRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapUpResponse'
        '404':
          description: Operator not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators:
    post:
      tags:
      - Operators
      summary: Register an operator
      description: Create an operator entity with profile and initial offline status.
      operationId: create-operator
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOperatorRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorResponse'
        '401':
          description: Missing or invalid API key.
        '403':
          description: Insufficient permissions.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
    get:
      tags:
      - Operators
      summary: List operators
      description: List all operator entities for a workspace.
      operationId: list-operators
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          default: 10
          title: Limit
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Continuation Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_OperatorResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/operators/{operator_id}:
    get:
      tags:
      - Operators
      summary: Get an operator
      description: Get operator entity with computed state (profile, availability, performance).
      operationId: get-operator
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorResponse'
        '404':
          description: Operator not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Operators
      summary: Update an operator
      description: Update operator profile fields or status. Each change writes a world event.
      operationId: update-operator
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: operator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Operator Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOperatorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorResponse'
        '404':
          description: Operator not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SendGuidanceResponse:
      properties:
        status:
          type: string
          enum:
          - delivered
          - queued_no_subscriber
          - deduplicated
          - failed
          - unknown
          title: Status
          description: Delivery status
        call_sid:
          type: string
          title: Call Sid
          description: Call SID the guidance was sent to
      type: object
      required:
      - status
      - call_sid
      title: SendGuidanceResponse
    PaginatedResponse_EscalationEventResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/EscalationEventResponse'
          type: array
          title: Items
        has_more:
          type: boolean
          title: Has More
        continuation_token:
          anyOf:
          - type: integer
          - type: 'null'
          title: Continuation Token
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
      type: object
      required:
      - items
      - has_more
      title: PaginatedResponse[EscalationEventResponse]
    AccessTokenResponse:
      properties:
        token:
          type: string
          title: Token
        identity:
          type: string
          title: Identity
        conference_sid:
          type: string
          title: Conference Sid
        connect_params:
          additionalProperties:
            type: string
          type: object
          title: Connect Params
          default: {}
      type: object
      required:
      - token
      - identity
      - conference_sid
      title: AccessTokenResponse
    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
    OperatorPerformanceItem:
      properties:
        operator_id:
          type: string
          format: uuid
          title: Operator Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Display name
        status:
          type: string
          enum:
          - online
          - busy
          - offline
          title: Status
          description: Current availability
        total_escalations_handled:
          type: integer
          title: Total Escalations Handled
          description: Lifetime escalation count
        avg_handle_time_seconds:
          type: number
          title: Avg Handle Time Seconds
          description: Average handle time in seconds
        last_call_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Call At
          description: ISO-8601 timestamp of last call
      type: object
      required:
      - operator_id
      - status
      - total_escalations_handled
      - avg_handle_time_seconds
      title: OperatorPerformanceItem
    SwitchModeResponse:
      properties:
        mode:
          type: string
          enum:
          - listen
          - takeover
          title: Mode
          description: New operator mode
      type: object
      required:
      - mode
      title: SwitchModeResponse
    BriefingResponse:
      properties:
        call_sid:
          type: string
          title: Call Sid
        operator_id:
          type: string
          format: uuid
          title: Operator Id
        sections:
          items:
            $ref: '#/components/schemas/BriefingSection'
          type: array
          title: Sections
        generated_at:
          type: string
          format: date-time
          title: Generated At
      type: object
      required:
      - call_sid
      - operator_id
      - sections
      - generated_at
      title: BriefingResponse
      description: Structured operator briefing for a call.
    LeaveCallResponse:
      properties:
        success:
          type: boolean
          title: Success
      type: object
      required:
      - success
      title: LeaveCallResponse
    PriorityQueueItem:
      properties:
        call_sid:
          type: string
          title: Call Sid
          description: Twilio call SID
        caller_id:
          type: string
          title: Caller Id
          description: Caller phone number
          default: ''
        caller_phone:
          anyOf:
          - type: string
            maxLength: 16
            pattern: ^\+[1-9]\d{1,14}$
          - type: 'null'
          title: Caller Phone
          description: Caller E.164 phone number for console clients
        service_id:
          type: string
          title: Service Id
          description: Service ID handling the call
          default: ''
        service_name:
          anyOf:
          - $ref: '#/components/schemas/NameString'
          - type: 'null'
          description: Human-readable service name when available
        direction:
          type: string
          enum:
          - inbound
          - outbound
          - playground
          - simulated
          - test
          title: Direction
          description: Call direction
          default: inbound
        data_quality_flags:
          items:
            type: string
            const: invalid_direction
          type: array
          title: Data Quality Flags
          default: []
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When the active call started
        priority_score:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Priority Score
          description: Priority score normalized to 0.0-1.0
        priority_reasons:
          items:
            type: string
            enum:
            - high_risk
            - long_wait
            - negative_emotion
            - safety_concern
            - looping
          type: array
          title: Priority Reasons
          default: []
        wait_seconds:
          type: number
          title: Wait Seconds
          default: 0.0
        risk_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Risk Score
        risk_level:
          anyOf:
          - type: string
            enum:
            - low
            - medium
            - high
            - critical
          - type: 'null'
          title: Risk Level
        current_emotion:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Emotion
        current_valence:
          anyOf:
          - type: number
          - type: 'null'
          title: Current Valence
        current_state:
          type: string
          title: Current State
          default: ''
        turn_count:
          type: integer
          title: Turn Count
          default: 0
        escalation_active:
          type: boolean
          title: Escalation Active
          default: false
        entity_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Name
        brief_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Brief Context
      type: object
      required:
      - call_sid
      - priority_score
      title: PriorityQueueItem
      description: An active call ranked by operator priority.
    BriefingSection:
      properties:
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
      type: object
      required:
      - title
      - content
      title: BriefingSection
      description: A named section of the operator briefing.
    PhoneE164:
      type: string
      maxLength: 16
      minLength: 2
    JoinCallResponse:
      properties:
        participant_call_sid:
          type: string
          title: Participant Call Sid
          description: Twilio participant call SID
        conference_sid:
          type: string
          title: Conference Sid
          description: Twilio conference SID
        mode:
          type: string
          enum:
          - listen
          - takeover
          title: Mode
          description: 'Operator mode: listen or takeover'
        operator_entity_id:
          type: string
          format: uuid
          title: Operator Entity Id
          description: World entity ID of the operator
      type: object
      required:
      - participant_call_sid
      - conference_sid
      - mode
      - operator_entity_id
      title: JoinCallResponse
      description: Confirmation of operator joining a call's conference.
    JoinCallRequest:
      properties:
        call_sid:
          type: string
          maxLength: 64
          minLength: 1
          title: Call Sid
        mode:
          type: string
          enum:
          - listen
          - takeover
          title: Mode
          default: takeover
      type: object
      required:
      - call_sid
      tit

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