Calls
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Start date (inclusive)
End date (inclusive)
Filter by call status
Filter by direction (inbound, outbound, playground, simulated)
Minimum duration in seconds
Maximum duration in seconds
Filter by service ID
Include simulated sessions
false200Alias for offset (pagination cursor)
Successful Response
Validation Error
GET /v1/{workspace_id}/calls HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"call_sid": "text",
"direction": "inbound",
"phone_number": "text",
"caller_id": "text",
"started_at": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"status": "initiated",
"escalation_status": "text",
"turns": 1,
"has_recording": true,
"quality_score": 1,
"final_state": "text",
"completion_reason": "completed",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"source": "real",
"run_id": "text",
"parent_session_id": "text",
"fork_turn_index": 1
}
],
"total": 1,
"has_more": true,
"continuation_token": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
30Successful Response
E.164 phone number
Total calls across the period
Inbound call count
Outbound call count
Average call duration
Validation Error
GET /v1/{workspace_id}/calls/phone-volume HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"phone_number": "text",
"total_calls": 1,
"inbound": 1,
"outbound": 1,
"avg_duration_seconds": 1,
"by_date": [
{
"date": "text",
"count": 1
}
]
}
]API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Lookback period in days
30Successful Response
Workspace-level call quality benchmarks for contextual comparison.
00Validation Error
GET /v1/{workspace_id}/calls/benchmarks HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"avg_quality_score": 1,
"p50_quality_score": 1,
"p25_quality_score": 1,
"p75_quality_score": 1,
"total_calls": 0,
"avg_duration_seconds": 1,
"escalation_rate": 0,
"quality_distribution": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
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.
World entity ID for the call
Twilio call SID
Call direction
inboundPossible values: Call duration in seconds
0Quality score 0.0 to 1.0
Why the call ended
Final conversation state name
When intelligence was computed
Intelligence data not found for this call
Validation Error
GET /v1/{workspace_id}/calls/{call_id}/intelligence HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"call_id": "text",
"call_sid": "text",
"direction": "inbound",
"duration_seconds": 0,
"quality_score": 1,
"quality_breakdown": {
"score": 1,
"components": [
{
"name": "latency",
"penalty": 1,
"value": 1,
"threshold": "text",
"severity": "none"
}
],
"workspace_avg": 1,
"workspace_percentile": 1
},
"key_moments": [
{
"turn": 1,
"type": "latency_spike",
"severity": "warning",
"description": "text"
}
],
"emotion_summary": {
"dominant_emotion": "text",
"average_valence": 1,
"average_arousal": 1,
"peak_negative_valence": 1,
"barge_in_count": 0
},
"risk_summary": {
"composite_score": 0,
"level": "low"
},
"latency_summary": {
"avg_engine_ms": 1,
"p50_engine_ms": 1,
"p95_engine_ms": 1,
"avg_audio_ttfb_ms": 1,
"p50_audio_ttfb_ms": 1,
"p95_audio_ttfb_ms": 1,
"avg_nav_ms": 1,
"avg_render_ms": 1,
"turn_count": 1,
"silence_ratio": 1
},
"conversation_summary": {
"turn_count": 0,
"states_visited_count": 0,
"unique_states": 0,
"loop_count": 0,
"barge_in_count": 0
},
"tool_summary": {
"total_calls": 0,
"succeeded": 0,
"failed": 0,
"failure_rate": 0
},
"safety_summary": {
"match_count": 0
},
"operator_summary": {
"escalated": false,
"operator_active": true
},
"completion_reason": "completed",
"final_state": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Filter by overall outcome
Only include analyses computed at or after this time
Only include analyses computed strictly before this time
Max rows per page (1-100)
20Offset from the previous page (0 for the first page)
0Successful Response
Paginated list response for trace analyses.
Whether more rows are available beyond this page
falseToken to pass as continuation_token for the next page (None when exhausted)
Invalid query parameters
Analytics warehouse query failed
Analytics warehouse not configured
GET /v1/{workspace_id}/calls/traces HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"call_sid": "text",
"call_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"outcome": "succeeded",
"summary": "text",
"emotional_arc": "text",
"key_moment_count": 0,
"computed_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": false,
"continuation_token": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request body for creating an outbound call.
use_case_id is required: channel-manager selects the optimal outbound
phone number bound to that use case (the sole caller-ID resolution path).
Destination phone number in E.164 format.
Channel-manager use case ID. channel-manager selects the optimal outbound phone number bound to this use case.
Patient entity UUID in the world model. Must exist in workspace as a person entity. Provide either patient_entity_id or patient_canonical_id.
Patient world model canonical_id of the form 'source:resource_type:id' (e.g. 'charmhealth:Patient:67890'). The structural regex on CanonicalIdString rejects spaces, names, DOBs, and similar regulated content so PHI cannot leak into audit events or pipeline projections. The raw value is deliberately not recorded in the outbound.initiated event — correlation back to the source system is via the resolved entity_id joined to world.entities_synced.canonical_id. Resolved against the SDP-projected world.entities_synced table; an entity created moments ago may not yet be visible if the projection is lagging. Provide either patient_entity_id or patient_canonical_id, not both.
^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$Why the call is being made (e.g. appointment_reminder, follow_up, lab_results).
Service ID for the voice agent to use.
Optional system prompt override for this call.
What the call should accomplish. Injected into agent context.
Classification tags for analytics.
Prior call_sid if this is a callback from a previous call.
Client-provided idempotency key. Auto-generated if omitted.
World model outbound_task entity ID for completion feedback.
Successful Response
Response from creating an outbound call.
Twilio call SID for the outbound call
Initial call status (typically 'queued')
Resolved caller ID when use_case_id was used.
Channel-manager setup ID when use_case_id was used.
World event ID for the outbound.initiated event.
Invalid phone number format
No phone number available for use case
Validation Error
Rate limit exceeded
Upstream Twilio or voice agent error
Voice agent, outbound calls, or channel manager not configured
Channel manager phone selection timed out
POST /v1/{workspace_id}/calls/outbound HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 449
{
"phone_to": "text",
"use_case_id": "123e4567-e89b-12d3-a456-426614174000",
"patient_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"patient_canonical_id": "text",
"reason": "text",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"system_prompt": "text",
"goal": "text",
"tags": [
"text"
],
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"derived_from_call_sid": "text",
"idempotency_key": "text",
"outbound_task_entity_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"call_sid": "text",
"status": "text",
"phone_from": "text",
"setup_id": "123e4567-e89b-12d3-a456-426614174000",
"event_id": "123e4567-e89b-12d3-a456-426614174000"
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[A-Za-z0-9][A-Za-z0-9_-]*$Analysis ready or status indicating progress
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.
Call identifier (Twilio call SID or direct session ID)
ready: analysis complete. pending: call completed, analysis processing. unavailable: analysis not possible for this call.
readyPossible values: 2-3 sentence narrative of the call - the emotional story, not just what happened
Overall call outcome
Number of key decision moments identified (typically 3-8)
0Caller emotional trajectory as a readable sequence (e.g. 'curious -> confused -> frustrated -> relieved')
Synthesis of why this call went the way it did - combining audio perception with execution data
Moments where the agent could have taken a better action
Cross-call or cross-turn patterns detected by the analysis
UUID string of the associated world.entities_synced call row (if resolved)
When the analysis was produced by the pipeline
Call not found in this workspace
Validation Error
Analytics warehouse not configured
GET /v1/{workspace_id}/calls/{call_id}/trace-analysis HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"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."
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[A-Za-z0-9][A-Za-z0-9_-]*$Max metric values to return
100Successful Response
Validation Error
GET /v1/{workspace_id}/calls/{call_id}/metrics HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"metrics": [
{
"metric_key": "text",
"source": "production",
"entity_type": "text",
"entity_id": "text",
"service_id": "text",
"run_id": "text",
"session_id": "text",
"period_start": "2026-01-01T00:00:00.000Z",
"period_end": "2026-01-01T00:00:00.000Z",
"event_count": 1,
"avg_confidence": 1,
"unit": "text",
"computed_at": "2026-01-01T00:00:00.000Z",
"metric_type": "text",
"value": 1
}
]
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[A-Za-z0-9][A-Za-z0-9_-]*$Successful Response
000Call not found
Validation Error
GET /v1/{workspace_id}/calls/{call_id}/timeline HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"turns": [
{
"turn_index": 1,
"seek_to": 1,
"active_start": 1,
"active_end": 1
}
],
"segments": [
{
"type": "agent_speech",
"lane": "agent",
"track": "agent",
"lane_id": "text",
"order": 1,
"actor": {
"kind": "agent",
"role": "agent",
"label": "text",
"participant_id": "text"
},
"start": 1,
"end": 1,
"label": "text",
"turn_index": 1,
"stt_confidence": 1,
"eot_confidence": 1,
"audio_window_start": 1,
"audio_window_end": 1,
"engine_ms": 1,
"nav_ms": 1,
"render_ms": 1,
"audio_ttfb_ms": 1,
"e2e_ttfb_ms": 1,
"tool_name": "text",
"call_id": "text",
"parent_call_id": "text",
"integration_name": "text",
"endpoint_name": "text",
"protocol": "text",
"succeeded": true,
"duration_ms": 1,
"from_state": "text",
"to_state": "text",
"emotion": "text",
"valence": 1,
"state": "text"
}
],
"duration_seconds": 1,
"timebase": {
"unit": "seconds",
"origin": "media_start",
"start": 0,
"end": 0
},
"lanes": [
{
"id": "text",
"track": "agent",
"label": "text",
"order": 1,
"actor": {
"kind": "agent",
"role": "agent",
"label": "text",
"participant_id": "text"
}
}
],
"total_user_speech_seconds": 0,
"total_agent_speech_seconds": 0,
"total_silence_seconds": 0,
"avg_processing_gap_ms": 1,
"max_processing_gap_ms": 1,
"avg_perceived_latency_ms": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Full call detail — the canonical response for GET /calls/{call_id}.
This is the single source of truth for the call detail shape. The OpenAPI spec is generated from this model. The SDK TypeScript types are generated from the spec. The developer-console consumes SDK types directly.
completed0[][]falseCall not found
Validation Error
GET /v1/{workspace_id}/calls/{call_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"call_sid": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"caller_id": "text",
"phone_number": "text",
"direction": "inbound",
"status": "completed",
"error": "text",
"call_start_time": "2026-01-01T00:00:00.000Z",
"call_end_time": "2026-01-01T00:00:00.000Z",
"call_duration_seconds": 0,
"media_start_time": "2026-01-01T00:00:00.000Z",
"config": {
"agent_id": "123e4567-e89b-12d3-a456-426614174000",
"agent_version": 1,
"agent_name": "text",
"context_graph_id": "123e4567-e89b-12d3-a456-426614174000",
"context_graph_version": 1,
"initial_state": "text",
"gpt_audio_model": "text",
"navigation_model": "text"
},
"turns": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"trigger": "",
"user_transcript": "text",
"agent_transcript": "text",
"agent_action": "text",
"interrupted": false,
"filler_type": "text",
"speaker_id": "text",
"speaker_role": "text",
"emotion_label": "text",
"emotion_valence": 1,
"compound_emotions": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"stt_confidence": 1,
"eot_confidence": 1,
"state": "",
"tool_calls": [
{
"tool_name": "text",
"call_id": "text",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"output": "text",
"output_truncated": false,
"output_original_length": 1,
"output_truncated_to": 1,
"duration_ms": 1,
"succeeded": true,
"error_message": "text",
"integration_name": "text",
"endpoint_name": "text",
"protocol": "text"
}
],
"state_transitions": [
{
"type": "text",
"previous_state": "",
"next_state": "",
"annotation": "text",
"nav_ms": 1,
"from_state": "text",
"to_state": "text"
}
],
"inner_thoughts": [
"text"
],
"timestamp": "2026-01-01T00:00:00.000Z",
"engine_ms": 1,
"user_speech_start_ms": 1,
"user_speech_end_ms": 1,
"agent_speech_start_ms": 1,
"agent_speech_end_ms": 1,
"audio_window_start_ms": 1,
"audio_window_end_ms": 1,
"nav_ms": 1,
"render_ms": 1,
"audio_ttfb_ms": 1,
"signal_kind": "text",
"signal_source": "text",
"state_before": "text",
"state_after": "text",
"primary_effect_kind": "text",
"tool_name": "text",
"tool_succeeded": true,
"tool_ms": 1,
"modality": "text",
"empathy_tier": 1,
"decision_bearing": true
}
],
"states_visited": [
"text"
],
"final_state": "text",
"triggered_behaviors": [
"text"
],
"completion_reason": "completed",
"emotional_summary": {
"dominant_emotion": "text",
"average_valence": 1,
"average_arousal": 1,
"peak_negative_valence": 1,
"peak_negative_emotion": "text",
"emotional_shifts": 1,
"final_trend": "text",
"segment_count": 1,
"barge_in_count": 1,
"compound_emotions": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]
},
"forwarding": {
"forward_to": "text",
"should_disconnect": true,
"warm_transfer": true,
"forwarded_at": "2026-01-01T00:00:00.000Z"
},
"conference_sid": "text",
"participants": [
{
"participant_id": "text",
"role": "caller",
"display_name": "text",
"phone_number": "text",
"joined_at": "2026-01-01T00:00:00.000Z",
"left_at": "2026-01-01T00:00:00.000Z"
}
],
"barge_in_events": [
{
"type": "barge_in",
"interrupted_text": "text",
"discarded_texts": [
"text"
],
"interrupted_speaker_id": "text",
"interrupting_speaker_id": "text",
"total_barge_ins": 1
}
],
"recording_path": "text",
"twilio_recording_sid": "text",
"twilio_recording_duration": 1,
"has_recording": false,
"timeline": {
"turns": [
{
"turn_index": 1,
"seek_to": 1,
"active_start": 1,
"active_end": 1
}
],
"segments": [
{
"type": "agent_speech",
"lane": "agent",
"track": "agent",
"lane_id": "text",
"order": 1,
"actor": {
"kind": "agent",
"role": "agent",
"label": "text",
"participant_id": "text"
},
"start": 1,
"end": 1,
"label": "text",
"turn_index": 1,
"stt_confidence": 1,
"eot_confidence": 1,
"audio_window_start": 1,
"audio_window_end": 1,
"engine_ms": 1,
"nav_ms": 1,
"render_ms": 1,
"audio_ttfb_ms": 1,
"e2e_ttfb_ms": 1,
"tool_name": "text",
"call_id": "text",
"parent_call_id": "text",
"integration_name": "text",
"endpoint_name": "text",
"protocol": "text",
"succeeded": true,
"duration_ms": 1,
"from_state": "text",
"to_state": "text",
"emotion": "text",
"valence": 1,
"state": "text"
}
],
"duration_seconds": 1,
"timebase": {
"unit": "seconds",
"origin": "media_start",
"start": 0,
"end": 0
},
"lanes": [
{
"id": "text",
"track": "agent",
"label": "text",
"order": 1,
"actor": {
"kind": "agent",
"role": "agent",
"label": "text",
"participant_id": "text"
}
}
],
"total_user_speech_seconds": 0,
"total_agent_speech_seconds": 0,
"total_silence_seconds": 0,
"avg_processing_gap_ms": 1,
"max_processing_gap_ms": 1,
"avg_perceived_latency_ms": 1
},
"verified_transcript": "text",
"verified_words": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"transcript_accuracy": 1,
"per_turn_accuracy": [
1
],
"call_analysis": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"source": "real",
"run_id": "text",
"score": 1,
"score_rationale": "text",
"parent_session_id": "text",
"fork_turn_index": 1,
"escalation": {
"status": "none",
"escalation_id": "text",
"requested_at": "2026-01-01T00:00:00.000Z",
"connected_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"trigger": "text",
"trigger_source": "text",
"concept": "text",
"similarity": 1,
"agent_confidence": 1,
"operator_type": "text",
"regulatory_basis": "text",
"immediate": false,
"risk_score": 1,
"operator_entity_id": "text",
"wait_seconds": 1,
"handle_time_seconds": 1,
"human_segment_turn_count": 1
},
"safety": {
"peak_concern_level": 0,
"concern_turn_count": 0,
"trajectory": "text",
"triage_history": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"concept_matches": [
{
"concept": "text",
"similarity": 1,
"agent_action": "text",
"agent_confidence": 1,
"agent_reasoning": "text",
"at": "2026-01-01T00:00:00.000Z"
}
]
},
"human_segments": [
{
"speaker_role": "text",
"transcript": "text",
"timestamp": "2026-01-01T00:00:00.000Z"
}
],
"audit": {
"event_count": 0,
"latest_event": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"quality_score": 1,
"conversation_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"safety_summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}Last updated
Was this helpful?