Amigo Operators API

openapi: 3.2.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:
    TranscriptSegment:
      properties:
        speaker_role:
          type: string
          title: Speaker Role
        transcript:
          type: string
          title: Transcript
        timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Timestamp
        escalation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Escalation Id
        confidence:
          type: number
          title: Confidence
      type: object
      required:
      - speaker_role
      - transcript
      - timestamp
      - escalation_id
      - confidence
      title: TranscriptSegment
    SwitchModeResponse:
      properties:
        mode:
          type: string
          enum:
          - listen
          - takeover
          title: Mode
          description: New operator mode
      type: object
      required:
      - mode
      title: SwitchModeResponse
    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]
    EscalationStatsBucket:
      properties:
        key:
          type: string
          title: Key
        count:
          type: integer
          title: Count
      type: object
      required:
      - key
      - count
      title: EscalationStatsBucket
    PaginatedResponse_OperatorResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/OperatorResponse'
          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[OperatorResponse]
    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
    WrapUpResponse:
      properties:
        success:
          type: boolean
          title: Success
      type: object
      required:
      - success
      title: WrapUpResponse
    EscalationEventResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
        event_type:
          type: string
          title: Event Type
          description: Event type (e.g. escalation.requested, escalation.connected)
        data:
          additionalProperties: true
          type: object
          title: Data
          description: Event payload — shape varies by event_type
        source:
          type: string
          title: Source
          description: System that emitted the event
        confidence:
          type: number
          title: Confidence
          description: Confidence score 0.0 to 1.0
        ingested_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Ingested At
          description: When the event was ingested
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the event occurred
      type: object
      required:
      - id
      - workspace_id
      - event_type
      - data
      - source
      - confidence
      title: EscalationEventResponse
    PhoneE164:
      type: string
      maxLength: 16
      minLength: 2
    OperatorStatusCounts:
      properties:
        total:
          type: integer
          title: Total
        online:
          type: integer
          title: Online
        busy:
          type: integer
          title: Busy
        offline:
          type: integer
          title: Offline
      type: object
      required:
      - total
      - online
      - busy
      - offline
      title: OperatorStatusCounts
    OperatorResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Display name
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Contact email
        type:
          anyOf:
          - type: string
            enum:
            - clinical
            - administrative
            - crisis_counselor
          - type: 'null'
          title: Type
          description: Operator specialization
        skills:
          items:
            type: string
          type: array
          title: Skills
          description: Skill tags for routing
        connection_method:
          type: string
          enum:
          - browser
          - phone
          title: Connection Method
          description: How the operator connects to calls
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
          description: E.164 phone number for phone-based operators
        role:
          type: string
          enum:
          - operator
          - supervisor
          - admin
          title: Role
          description: Permission role
        status:
          type: string
          enum:
          - online
          - busy
          - offline
          title: Status
          description: Current availability
        last_status_change:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Status Change
          description: ISO-8601 timestamp of last status transition
        active_call_sid:
          anyOf:
          - type: string
          - type: 'null'
          title: Active Call Sid
          description: Call SID if currently on a call
        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 escalation handle time in seconds
        last_call_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Call At
          description: ISO-8601 timestamp of last call
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the operator was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: When the operator was last updated
      type: object
      required:
      - id
      - workspace_id
      - skills
      - connection_method
      - role
      - status
      - total_escalations_handled
      - avg_handle_time_seconds
      title: OperatorResponse
    PerformanceSummaryResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
        total_operators:
          type: integer
          title: Total Operators
        online:
          type: integer
          title: Online
        busy:
          type: integer
          title: Busy
        offline:
          type: integer
          title: Offline
        total_escalations_handled:
          type: integer
          title: Total Escalations Handled
        avg_handle_time_seconds:
          type: number
          title: Avg Handle Time Seconds
        operators:
          items:
            $ref: '#/components/schemas/OperatorPerformanceItem'
          type: array
          title: Operators
      type: object
      required:
      - workspace_id
      - total_operators
      - online
      - busy
      - offline
      - total_escalations_handled
      - avg_handle_time_seconds
      - operators
      title: PerformanceSummaryResponse
    DashboardResponse:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
        operators:
          $ref: '#/components/schemas/OperatorStatusCounts'
        active_escalations:
       

# --- 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