Amigo Calls API

openapi: 3.2.0
info:
  title: Amigo Account Calls 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: Calls
paths:
  /v1/{workspace_id}/calls:
    get:
      tags:
      - Calls
      summary: List calls with filters
      description: Query call entities with date range, status, and duration filters. Enriched with quality_score and final_state from call_intelligence.
      operationId: list-calls
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date (inclusive)
          title: Date From
        description: Start date (inclusive)
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date (inclusive)
          title: Date To
        description: End date (inclusive)
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by call status
          title: Status
        description: Filter by call status
      - name: direction
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by direction (inbound, outbound, playground, simulated)
          title: Direction
        description: Filter by direction (inbound, outbound, playground, simulated)
      - name: min_duration
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Minimum duration in seconds
          title: Min Duration
        description: Minimum duration in seconds
      - name: max_duration
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum duration in seconds
          title: Max Duration
        description: Maximum duration in seconds
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by service ID
          title: Service Id
        description: Filter by service ID
      - name: include_simulated
        in: query
        required: false
        schema:
          type: boolean
          description: Include simulated sessions
          default: false
          title: Include Simulated
        description: Include simulated sessions
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: continuation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Alias for offset (pagination cursor)
          title: Continuation Token
        description: Alias for offset (pagination cursor)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/phone-volume:
    get:
      tags:
      - Calls
      summary: Call volume per phone number
      description: Aggregated call counts and durations grouped by phone number.
      operationId: get-phone-call-volume
      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:
                type: array
                items:
                  $ref: '#/components/schemas/PhoneNumberCallVolume'
                title: Response Get-Phone-Call-Volume
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/benchmarks:
    get:
      tags:
      - Calls
      summary: Workspace call quality benchmarks
      description: Aggregate quality benchmarks for the workspace. Used by call detail to show 'vs workspace average' and by call list for quality context.
      operationId: get-call-benchmarks
      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: Lookback period in days
          default: 30
          title: Days
        description: Lookback period in days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBenchmarks'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/{call_id}/intelligence:
    get:
      tags:
      - Calls
      summary: Call intelligence profile (Layer 4 narrative)
      description: 'Aggregated intelligence for a completed call: quality breakdown, key moments, and summaries. Per-turn visualization lives on the unified timeline (call detail endpoint → timeline.segments).'
      operationId: get-call-intelligence
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallIntelligenceDetail'
        '404':
          description: Intelligence data not found for this call
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/traces:
    get:
      tags:
      - Calls
      summary: List trace analyses
      description: Paginated list of trace analyses for the workspace. Use this instead of paginating `/calls` and fetching traces one-by-one (N+1).
      operationId: list-call-traces
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: outcome
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - succeeded
            - partially
            - failed
            - abandoned
            type: string
          - type: 'null'
          description: Filter by overall outcome
          title: Outcome
        description: Filter by overall outcome
      - name: min_computed_at
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only include analyses computed at or after this time
          title: Min Computed At
        description: Only include analyses computed at or after this time
      - name: max_computed_at
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only include analyses computed strictly before this time
          title: Max Computed At
        description: Only include analyses computed strictly before this time
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          description: Max rows per page (1-100)
          default: 20
          title: Limit
        description: Max rows per page (1-100)
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Offset from the previous page (0 for the first page)
          default: 0
          title: Continuation Token
        description: Offset from the previous page (0 for the first page)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceAnalysisListResponse'
        '503':
          description: Analytics warehouse not configured
        '502':
          description: Analytics warehouse query failed
        '422':
          description: Invalid query parameters
  /v1/{workspace_id}/calls/outbound:
    post:
      tags:
      - Calls
      summary: Create an outbound call
      description: Initiate an outbound voice call from a workspace phone number. channel-manager selects the optimal number for the given use_case_id. Supports idempotency via the idempotency_key field.
      operationId: create-outbound-call
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOutboundCallRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOutboundCallResponse'
        '400':
          description: Invalid phone number format
        '404':
          description: No phone number available for use case
        '503':
          description: Voice agent, outbound calls, or channel manager not configured
        '429':
          description: Rate limit exceeded
        '504':
          description: Channel manager phone selection timed out
        '502':
          description: Upstream Twilio or voice agent error
        '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
  /v1/{workspace_id}/calls/{call_id}/trace-analysis:
    get:
      tags:
      - Calls
      summary: Deep call understanding
      description: 'Audio-native intelligence for a completed call: emotional arc, key decision moments with causal attribution, counterfactual reasoning, and actionable coaching. Produced by the Amigo intelligence pipeline from the raw call recording.


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


        **Status values**: `ready` = analysis complete, `pending` = analysis started on first request (typically ready in 2-5 minutes; poll again), `unavailable` = no recording or analysis transiently unavailable (retry later).'
      operationId: get-call-trace-analysis
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$
          title: Call Id
      responses:
        '200':
          description: Analysis ready or status indicating progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceAnalysisResponse'
        '404':
          description: Call not found in this workspace
        '503':
          description: Analytics warehouse not configured
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/{call_id}/metrics:
    get:
      tags:
      - Calls
      summary: Call metric values
      description: Latest per-call realtime metric values for the call detail sidebar.
      operationId: list-call-metric-values
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$
          title: Call Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max metric values to return
          default: 100
          title: Limit
        description: Max metric values to return
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/{call_id}/timeline:
    get:
      tags:
      - Calls
      summary: Call playback timeline
      description: Canonical playback timeline for the call detail visualization. This is the same strongly typed timeline model embedded in the call detail response, exposed directly for timeline-only consumers.
      operationId: get-call-timeline
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaybackTimeline'
        '404':
          description: Call not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/calls/{call_id}:
    get:
      tags:
      - Calls
      summary: Call detail
      description: Full call detail including turns, escalation state, safety state, and recording info. Proxied from voice-agent, with simulation session fallback.
      operationId: get-call-detail
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallDetailResponse'
        '404':
          description: Call not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TraceAnalysisListItem:
      properties:
        call_sid:
          type: string
          maxLength: 128
          minLength: 1
          title: Call Sid
          description: Call identifier
        call_entity_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Call Entity Id
          description: Associated world.entities_synced call row UUID
        outcome:
          anyOf:
          - type: string
            enum:
            - succeeded
            - partially
            - failed
            - abandoned
          - type: 'null'
          title: Outcome
          description: Overall call outcome
        summary:
          anyOf:
          - type: string
            maxLength: 2000
            minLength: 1
          - type: 'null'
          title: Summary
          description: Short call summary
        emotional_arc:
          anyOf:
          - type: string
            maxLength: 2000
            minLength: 1
          - type: 'null'
          title: Emotional Arc
          description: Caller emotional trajectory string
        key_moment_count:
          type: integer
          minimum: 0.0
          title: Key Moment Count
          description: Number of key moments identified
          default: 0
        computed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Computed At
          description: When the analysis was produced
      type: object
      required:
      - call_sid
      title: TraceAnalysisListItem
      description: Compact summary of a trace analysis row for list views.
    TraceAnalysisResponse:
      properties:
        call_sid:
          type: string
          maxLength: 128
          minLength: 1
          title: Call Sid
          description: Call identifier (Twilio call SID or direct session ID)
        status:
          type: string
          enum:
          - ready
          - pending
          - unavailable
          title: Status
          description: 'ready: analysis complete. pending: call completed, analysis processing. unavailable: analysis not possible for this call.'
          default: ready
        summary:
          anyOf:
          - type: string
            maxLength: 2000
            minLength: 1
          - type: 'null'
          title: Summary
          description: 2-3 sentence narrative of the call - the emotional story, not just what happened
        outcome:
          anyOf:
          - type: string
            enum:
            - succeeded
            - partially
            - failed
            - abandoned
          - type: 'null'
          title: Outcome
          description: Overall call outcome
        key_moment_count:
          type: integer
          minimum: 0.0
          title: Key Moment Count
          description: Number of key decision moments identified (typically 3-8)
          default: 0
        key_moments:
          items:
            $ref: '#/components/schemas/TraceKeyMoment'
          type: array
          maxItems: 100
          title: Key Moments
          description: Key decision points with causal attribution to audio inputs
        emotional_arc:
          anyOf:
          - type: string
            maxLength: 2000
            minLength: 1
          - type: 'null'
          title: Emotional Arc
          description: Caller emotional trajectory as a readable sequence (e.g. 'curious -> confused -> frustrated -> relieved')
        emotional_shifts:
          items:
            $ref: '#/components/schemas/EmotionalShift'
          type: array
          maxItems: 100
          title: Emotional Shifts
          description: Critical emotional state changes detected in the caller's voice
        interaction_dynamics:
          anyOf:
          - $ref: '#/components/schemas/InteractionDynamics'
          - type: 'null'
          description: System-level conversation flow analysis
        coaching:
          items:
            $ref: '#/components/schemas/CoachingItem'
          type: array
          maxItems: 50
          title: Coaching
          description: Specific, actionable agent improvements tied to exact moments in this call
        counterfactuals:
          items:
            $ref: '#/components/schemas/Counterfactual'
          type: array
          maxItems: 50
          title: Counterfactuals
          description: Alternative actions that would have meaningfully changed the outcome
        deep_understanding:
          anyOf:
          - type: string
            maxLength: 10000
            minLength: 1
          - type: 'null'
          title: Deep Understanding
          description: Synthesis of why this call went the way it did - combining audio perception with execution data
        signal_response_alignment:
          items:
            $ref: '#/components/schemas/SignalResponseAlignment'
          type: array
          maxItems: 50
          title: Signal Response Alignment
          description: 'Per-signal alignment analysis: whether the agent''s response matched each salient signal'
        missed_opportunities:
          items:
            type: string
            maxLength: 2000
            minLength: 1
          type: array
          maxItems: 50
          title: Missed Opportunities
          description: Moments where the agent could have taken a better action
        emergent_patterns:
          items:
            type: string
            maxLength: 2000
            minLength: 1
          type: array
          maxItems: 50
          title: Emergent Patterns
          description: Cross-call or cross-turn patterns detected by the analysis
        call_entity_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Call Entity Id
          description: UUID string of the associated world.entities_synced call row (if resolved)
        computed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Computed At
          description: When the analysis was produced by the pipeline
      type: object
      required:
      - call_sid
      title: TraceAnalysisResponse
      description: 'Deep call understanding produced by the Amigo intelligence pipeline.


        Analyzes the raw call audio to identify emotional dynamics, key decision

        moments, and actionable coaching - understanding that exceeds what either

        participant had during the call itself.


        **Latency note**: This endpoint reads from the analytics data warehouse.

        Expect 500ms-2s response time, not sub-10ms like transactional endpoints.'
      examples:
      - call_sid: CA493e4610386f87f43b02102068eb6ad3
        deep_understanding: The call failed not because of agent behavior but because of environmental factors - the caller was pulled into a side conversation that the agent could not compete with.
        emotional_arc: neutral -> cooperative -> distracted -> disengaged
        key_moment_count: 2
        outcome: abandoned
        status: ready
        summary: The caller initially cooperated with scheduling but became distracted by a nearby conversation, ultimately abandoning the call without booking.
    DecisionFactor:
      properties:
        factor:
          type: string
          maxLength: 2000
          minLength: 1
          title: Factor
          description: What specifically drove this decision - exact words heard or tone described
        source_type:
          type: string
          title: Source Type
          description: Category of the audio input
      type: object
      required:
      - factor
      - source_type
      title: DecisionFactor
      description: A specific audio input that drove an agent decision.
      examples:
      - factor: Caller said 'yes, Thursday works' with confident, faster speech
        source_type: transcript
    BooleanMetricValueResponse:
      properties:
        metric_key:
          type: string
          title: Metric Key
        source:
          type: string
          title: Source
          default: production
        entity_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Type
        entity_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Id
        service_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        period_start:
          type: string
          format: date-time
          title: Period Start
        period_end:
          type: string
          format: date-time
          title: Period End
        event_count:
          type: integer
          title: Event Count
        avg_confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Confidence
        unit:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Unit
        computed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Computed At
        metric_type:
          type: string
          const: boolean
          title: Metric Type
        value:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Value
      type: object
      required:
      - metric_key
      - period_start
      - period_end
      - event_count
      - metric_type
      - value
      title: BooleanMetricValueResponse
    DescriptionString:
      type: string
      maxLength: 2000
    KeyMoment:
      properties:
        turn:
          anyOf:
          - type: integer
          - type: 'null'
          title: Turn
          description: Turn index where the moment occurred
        type:
          type: string
          enum:
          - latency_spike
          - silence
          - barge_in
          - loop
          - tool_failure
          - escalation
          - safety_flag
          - high_risk
          - elevated_risk
          title: Type
          description: Category of the moment
        severity:
          type: string
          enum:
          - info
          - warning
          - error
          title: Severity
          description: Severity level
          default: warning
        description:
          type: string
          title: Description
          description: Human-readable description
      type: object
      required:
      - type
      - description
      title: KeyMoment
      description: Notable event during the call worth highlighting.
    SafetyState:
      properties:
        peak_concern_level:
          type: integer
          title: Peak Concern Level
          default: 0
        concern_turn_count:
          type: integer
          title: Concern Turn Count
          default: 0
        trajectory:
          anyOf:
          - type: string
          - type: 'null'
          title: Trajectory
        triage_history:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Triage History
          default: []
        concept_matches:
          items:
            $ref: '#/components/schemas/ConceptMatch'
          type: array
          title: Concept Matches
          default: []
      type: object
      title: SafetyState
    TraceAnalysisListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TraceAnalysisListItem'
          type: array
          title: Items
          description: Trace analysis summaries
        has_more:
          type: boolean
          title: Has More
          description: Whether more rows are available beyond this page
          default: false
        continuation_token:
          anyOf:
          - type: integer
          - type: 'null'
          title: Continuation Token
          description: Token to pass as ``continuation_token`` for the next page (None when exhausted)
      type: object
      title: TraceAnalysisListResponse
      description: Paginated list response for trace analyses.
    PhoneE164:
      type: string
      maxLength: 16
      minLength: 2
    ToolSummary:
      properties:
        total_calls:
          type: integer
          title: Total Calls
          description: Total tool invocations
          default: 0
        succeeded:
          type: integer
          title: Succeeded
          description: Successful tool invocations
          default: 0
        failed:
          type: integer
          title: Failed
          description: Failed tool invocations
          default: 0
        failure_rate:
          type: number
          title: Failure Rate
          description: Tool failure rate 0.0 to 1.0
          default: 0.0
      type: object
      title: ToolSummary
      description: 'Tool usage statistics.


        Free-form residual on the raw ``tool_summary`` JSONB:

        ``by_tool: list[{name, calls, succeeded, failed, avg_duration_ms}]``

        — per-tool breakdown. Not exposed via this typed shape.'
    BargeInEvent:
      properties:
        type:
          const: barge_in
          default: barge_in
          title: Type
          type: string
        interrupted_text:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Interrupted Text
          x-phi: true
        discarded_texts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          default: null
          title: Discarded Texts
          x-phi: true
        interrupted_speaker_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Interrupted Speaker Id
        interrupting_speaker_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Interrupting Speaker Id
        total_barge_ins:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Total Barge Ins
      title: BargeInEvent
      type: object
    ToolCall:
      properties:
        tool_name:
          type: string
          title: Tool Name
        call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Id
        input:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Input
        output:
          anyOf:
          - type: string
          - type: 'null'
          title: Output
        output_truncated:
          type: boolean
          title: Output Truncated
          default: false
        output_original_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Original Length
        output_truncated_to:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Truncated To
        duration_ms:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration Ms
        succeeded:
          type: boolean
          title: Succeeded
          default: true
        e

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