Amigo Calls API
The Calls API from Amigo — 10 operation(s) for calls.
The Calls API from Amigo — 10 operation(s) for calls.
openapi: 3.1.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:
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.
CanonicalIdString:
type: string
maxLength: 256
minLength: 3
pattern: ^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$
CallListResponse:
properties:
items:
items:
$ref: '#/components/schemas/CallSummary'
type: array
title: Items
total:
type: integer
title: Total
has_more:
type: boolean
title: Has More
continuation_token:
anyOf:
- type: integer
- type: 'null'
title: Continuation Token
type: object
required:
- items
- total
- has_more
title: CallListResponse
ConceptMatch:
properties:
concept:
anyOf:
- type: string
- type: 'null'
title: Concept
similarity:
anyOf:
- type: number
- type: 'null'
title: Similarity
agent_action:
anyOf:
- type: string
- type: 'null'
title: Agent Action
agent_confidence:
anyOf:
- type: number
- type: 'null'
title: Agent Confidence
agent_reasoning:
anyOf:
- type: string
- type: 'null'
title: Agent Reasoning
at:
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
title: At
type: object
title: ConceptMatch
EscalationState:
properties:
status:
type: string
title: Status
default: none
escalation_id:
anyOf:
- type: string
- type: 'null'
title: Escalation Id
requested_at:
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
title: Requested At
connected_at:
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
title: Connected At
completed_at:
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
title: Completed At
trigger:
anyOf:
- type: string
- type: 'null'
title: Trigger
trigger_source:
anyOf:
- type: string
- type: 'null'
title: Trigger Source
concept:
anyOf:
- type: string
- type: 'null'
title: Concept
similarity:
anyOf:
- type: number
- type: 'null'
title: Similarity
agent_confidence:
anyOf:
- type: number
- type: 'null'
title: Agent Confidence
operator_type:
anyOf:
- type: string
- type: 'null'
title: Operator Type
regulatory_basis:
anyOf:
- type: string
- type: 'null'
title: Regulatory Basis
immediate:
type: boolean
title: Immediate
default: false
risk_score:
anyOf:
- type: number
- type: 'null'
title: Risk Score
operator_entity_id:
anyOf:
- type: string
- type: 'null'
title: Operator Entity Id
wait_seconds:
anyOf:
- type: number
- type: 'null'
title: Wait Seconds
handle_time_seconds:
anyOf:
- type: number
- type: 'null'
title: Handle Time Seconds
human_segment_turn_count:
anyOf:
- type: integer
- type: 'null'
title: Human Segment Turn Count
type: object
title: EscalationState
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
ConversationSummary:
properties:
turn_count:
type: integer
title: Turn Count
description: Total turn count for the call
default: 0
states_visited_count:
type: integer
title: States Visited Count
description: Number of states visited (including repeats)
default: 0
unique_states:
type: integer
title: Unique States
description: Number of distinct states visited
default: 0
loop_count:
type: integer
title: Loop Count
description: Number of detected state loops
default: 0
barge_in_count:
type: integer
title: Barge In Count
description: Number of caller interruptions
default: 0
type: object
title: ConversationSummary
description: 'Conversation flow metrics.
Free-form residual on the raw ``conversation_summary`` JSONB:
``text_intelligence: dict`` (text-channel intelligence
sub-payload), and on the simulation path ``transcript_text:
str`` (PHI), ``tool_calls: list``, ``score``,
``score_rationale``, ``terminal_reached``, ``states_visited``.
Not exposed via this typed shape.'
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.
EmotionSummary:
properties:
dominant_emotion:
anyOf:
- type: string
maxLength: 256
- type: 'null'
title: Dominant Emotion
description: Most frequent emotion (e.g. 'neutral', 'happy', 'angry')
average_valence:
anyOf:
- type: number
- type: 'null'
title: Average Valence
description: Average emotional valence -1.0 to 1.0
average_arousal:
anyOf:
- type: number
- type: 'null'
title: Average Arousal
description: Average emotional arousal 0.0 to 1.0
peak_negative_valence:
anyOf:
- type: number
- type: 'null'
title: Peak Negative Valence
description: Most negative valence observed
barge_in_count:
type: integer
title: Barge In Count
description: Number of caller interruptions (emotion-tagged)
default: 0
type: object
title: EmotionSummary
description: 'Aggregated emotional analysis across the call.
Free-form residual on the raw ``emotion_summary`` JSONB:
``compound_emotions: list[{name, score}]``. Not exposed via this
typed shape — readers wanting it consume the JSONB endpoint.'
CreateOutboundCallResponse:
properties:
call_sid:
type: string
title: Call Sid
description: Twilio call SID for the outbound call
status:
type: string
title: Status
description: Initial call status (typically 'queued')
phone_from:
anyOf:
- type: string
- type: 'null'
title: Phone From
description: Resolved caller ID when use_case_id was used.
setup_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Setup Id
description: Channel-manager setup ID when use_case_id was used.
event_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Event Id
description: World event ID for the outbound.initiated event.
type: object
required:
- call_sid
- status
title: CreateOutboundCallResponse
description: Response from creating an outbound call.
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
CallIntelligenceDetail:
properties:
call_id:
type: string
title: Call Id
description: World entity ID for the call
call_sid:
anyOf:
- type: string
- type: 'null'
title: Call Sid
description: Twilio call SID
direction:
type: string
enum:
- inbound
- outbound
- playground
- simulated
- test
title: Direction
description: Call direction
default: inbound
duration_seconds:
type: number
title: Duration Seconds
description: Call duration in seconds
default: 0.0
quality_score:
anyOf:
- type: number
- type: 'null'
title: Quality Score
description: Quality score 0.0 to 1.0
quality_breakdown:
anyOf:
- $ref: '#/components/schemas/QualityBreakdown'
- type: 'null'
description: Detailed quality breakdown
key_moments:
items:
$ref: '#/components/schemas/KeyMoment'
type: array
title: Key Moments
description: Notable call events
emotion_summary:
anyOf:
- $ref: '#/components/schemas/EmotionSummary'
- type: 'null'
description: Emotional analysis
risk_summary:
anyOf:
- $ref: '#/components/schemas/RiskSummary'
- type: 'null'
description: Risk assessment
latency_summary:
anyOf:
- $ref: '#/components/schemas/LatencySummary'
- type: 'null'
description: Audio latency metrics
conversation_summary:
anyOf:
- $ref: '#/components/schemas/ConversationSummary'
- type: 'null'
description: Conversation flow metrics
tool_summary:
anyOf:
- $ref: '#/components/schemas/ToolSummary'
- type: 'null'
description: Tool usage statistics
safety_summary:
anyOf:
- $ref: '#/components/schemas/SafetySummary'
- type: 'null'
description: Safety filter results
operator_summary:
anyOf:
- $ref: '#/components/schemas/OperatorIntelligenceSummary'
- type: 'null'
description: Operator intervention
completion_reason:
anyOf:
- type: string
enum:
- completed
- abandoned
- escalated
- transferred
- timeout
- error
- voicemail
- no_answer
- caller_hangup
- forwarded
- terminal_state
- warm_transfer_completed
- no_inbound_audio
- cancelled
- type: 'null'
title: Completion Reason
description: Why the call ended
final_state:
anyOf:
- type: string
- type: 'null'
title: Final State
description: Final conversation state name
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: When intelligence was computed
type: object
required:
- call_id
title: CallIntelligenceDetail
description: 'Layer 4 (Narrative) intelligence for a completed call.
Aggregated summaries, quality breakdown, and key moments — the
interpretive layer. Per-turn visualization data lives on the unified
timeline (call detail → PlaybackTimeline.segments), not here.'
MetricListResponse:
properties:
metrics:
items:
oneOf:
- $ref: '#/components/schemas/NumericalMetricValueResponse'
- $ref: '#/components/schemas/CategoricalMetricValueResponse'
- $ref: '#/components/schemas/BooleanMetricValueResponse'
discriminator:
propertyName: metric_type
mapping:
boolean: '#/components/schemas/BooleanMetricValueResponse'
categorical: '#/components/schemas/Categorical
# --- 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