# Operators ## Operator dashboard overview > Live dashboard with operator status counts, active escalation queue, and today's escalation statistics. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"DashboardResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"operators":{"$ref":"#/components/schemas/OperatorStatusCounts"},"active_escalations":{"type":"integer","title":"Active Escalations"},"escalations_today":{"$ref":"#/components/schemas/EscalationDailyStats"},"recent_escalations":{"items":{"$ref":"#/components/schemas/ActiveEscalationItem"},"type":"array","title":"Recent Escalations"}},"type":"object","required":["workspace_id","operators","active_escalations","escalations_today","recent_escalations"],"title":"DashboardResponse"},"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"},"EscalationDailyStats":{"properties":{"requested":{"type":"integer","title":"Requested","default":0},"connected":{"type":"integer","title":"Connected","default":0},"completed":{"type":"integer","title":"Completed","default":0},"avg_wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Wait Seconds"},"avg_handle_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Handle Time Seconds"}},"type":"object","title":"EscalationDailyStats"},"ActiveEscalationItem":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id","description":"Escalation event ID"},"status":{"type":"string","maxLength":64,"title":"Status","description":"Current escalation state"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"What triggered the escalation"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source","description":"Source system of the trigger"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept","description":"Clinical concept that triggered escalation"},"operator_type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Operator Type","description":"Required operator specialization"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis","description":"Regulatory reason for escalation"},"immediate":{"type":"boolean","title":"Immediate","description":"Whether the escalation requires immediate attention"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score","description":"Risk score 0.0 to 1.0"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At","description":"ISO-8601 timestamp when escalation was requested"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At","description":"ISO-8601 timestamp when operator connected"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds","description":"Seconds the caller waited for an operator"},"operator_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Operator Entity Id","description":"Entity ID of the connected operator"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"ISO-8601 timestamp when the call started"}},"type":"object","required":["call_entity_id","status","immediate"],"title":"ActiveEscalationItem","description":"A call with an active escalation, enriched from projected state."}}},"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"}}]}}}} ``` ## Operator performance summary > Aggregate performance across all operators with per-operator breakdown. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"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"},"OperatorPerformanceItem":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name"},"status":{"type":"string","enum":["online","busy","offline"],"title":"Status","description":"Current availability"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled","description":"Lifetime escalation count"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds","description":"Average handle time in seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At","description":"ISO-8601 timestamp of last call"}},"type":"object","required":["operator_id","status","total_escalations_handled","avg_handle_time_seconds"],"title":"OperatorPerformanceItem"}}},"paths":{"/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"}}]}}}} ``` ## List active escalations > List calls with active escalations (status: requested or connected). ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_ActiveEscalationItem_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ActiveEscalationItem"},"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[ActiveEscalationItem]"},"ActiveEscalationItem":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id","description":"Escalation event ID"},"status":{"type":"string","maxLength":64,"title":"Status","description":"Current escalation state"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"What triggered the escalation"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source","description":"Source system of the trigger"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept","description":"Clinical concept that triggered escalation"},"operator_type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Operator Type","description":"Required operator specialization"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis","description":"Regulatory reason for escalation"},"immediate":{"type":"boolean","title":"Immediate","description":"Whether the escalation requires immediate attention"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score","description":"Risk score 0.0 to 1.0"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At","description":"ISO-8601 timestamp when escalation was requested"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At","description":"ISO-8601 timestamp when operator connected"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds","description":"Seconds the caller waited for an operator"},"operator_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Operator Entity Id","description":"Entity ID of the connected operator"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"ISO-8601 timestamp when the call started"}},"type":"object","required":["call_entity_id","status","immediate"],"title":"ActiveEscalationItem","description":"A call with an active escalation, enriched from projected state."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## Escalation statistics > Aggregated escalation statistics over a time period. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"EscalationStatsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"type":"string","title":"Period"},"group_by":{"type":"string","title":"Group By"},"buckets":{"items":{"$ref":"#/components/schemas/EscalationStatsBucket"},"type":"array","title":"Buckets"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["workspace_id","period","group_by","buckets","total"],"title":"EscalationStatsResponse"},"EscalationStatsBucket":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"EscalationStatsBucket"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## List escalation events > List escalation lifecycle events for a workspace. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"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]"},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## Query audit log > Query audit events (operator actions) for a workspace. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_AuditEventResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__operators_models__AuditEventResponse"},"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[AuditEventResponse]"},"src__routes__operators_models__AuditEventResponse":{"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":"Audit event type (e.g. operator.status_change)"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Audit payload — shape varies by event_type"},"source":{"type":"string","title":"Source","description":"System that emitted the event"},"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"],"title":"AuditEventResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## Get call transcript > Per-speaker transcript segments from operator takeover sessions. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CallTranscriptResponse":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"total_segments":{"type":"integer","title":"Total Segments"},"segments":{"items":{"$ref":"#/components/schemas/TranscriptSegment"},"type":"array","title":"Segments"}},"type":"object","required":["call_entity_id","call_sid","total_segments","segments"],"title":"CallTranscriptResponse"},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## Priority-ranked operator queue > Active calls ranked by operator priority: risk, wait time, emotion, loops, and safety concerns. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PriorityQueueResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"queue":{"items":{"$ref":"#/components/schemas/PriorityQueueItem"},"type":"array","title":"Queue"},"total_active":{"type":"integer","title":"Total Active"}},"type":"object","required":["workspace_id","queue","total_active"],"title":"PriorityQueueResponse"},"PriorityQueueItem":{"properties":{"call_sid":{"type":"string","title":"Call Sid","description":"Twilio call SID"},"caller_id":{"type":"string","title":"Caller Id","description":"Caller phone number","default":""},"caller_phone":{"anyOf":[{"type":"string","maxLength":16,"pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"title":"Caller Phone","description":"Caller E.164 phone number for console clients"},"service_id":{"type":"string","title":"Service Id","description":"Service ID handling the call","default":""},"service_name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Human-readable service name when available"},"direction":{"type":"string","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","description":"Call direction","default":"inbound"},"data_quality_flags":{"items":{"type":"string","const":"invalid_direction"},"type":"array","title":"Data Quality Flags","default":[]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the active call started"},"priority_score":{"type":"number","maximum":1,"minimum":0,"title":"Priority Score","description":"Priority score normalized to 0.0-1.0"},"priority_reasons":{"items":{"type":"string","enum":["high_risk","long_wait","negative_emotion","safety_concern","looping"]},"type":"array","title":"Priority Reasons","default":[]},"wait_seconds":{"type":"number","title":"Wait Seconds","default":0},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"risk_level":{"anyOf":[{"type":"string","enum":["low","medium","high","critical"]},{"type":"null"}],"title":"Risk Level"},"current_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Emotion"},"current_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Valence"},"current_state":{"type":"string","title":"Current State","default":""},"turn_count":{"type":"integer","title":"Turn Count","default":0},"escalation_active":{"type":"boolean","title":"Escalation Active","default":false},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"brief_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Context"}},"type":"object","required":["call_sid","priority_score"],"title":"PriorityQueueItem","description":"An active call ranked by operator priority."},"NameString":{"type":"string","maxLength":256,"minLength":1}}},"paths":{"/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"}}]}}}} ``` ## Generate operator briefing > Structured briefing for an operator about to join a call. Template-rendered from call intelligence and entity context. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BriefingRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"}},"type":"object","required":["call_sid"],"title":"BriefingRequest","description":"Request for operator briefing on a specific call."},"BriefingResponse":{"properties":{"call_sid":{"type":"string","title":"Call Sid"},"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"sections":{"items":{"$ref":"#/components/schemas/BriefingSection"},"type":"array","title":"Sections"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"}},"type":"object","required":["call_sid","operator_id","sections","generated_at"],"title":"BriefingResponse","description":"Structured operator briefing for a call."},"BriefingSection":{"properties":{"title":{"type":"string","title":"Title"},"content":{"type":"string","title":"Content"}},"type":"object","required":["title","content"],"title":"BriefingSection","description":"A named section of the operator briefing."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limit exceeded."}}}}}} ``` ## Join active call as operator > Add operator to an active call's Twilio Conference. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"JoinCallRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","default":"takeover"}},"type":"object","required":["call_sid"],"title":"JoinCallRequest","description":"Request to join an active call as operator."},"JoinCallResponse":{"properties":{"participant_call_sid":{"type":"string","title":"Participant Call Sid","description":"Twilio participant call SID"},"conference_sid":{"type":"string","title":"Conference Sid","description":"Twilio conference SID"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","description":"Operator mode: listen or takeover"},"operator_entity_id":{"type":"string","format":"uuid","title":"Operator Entity Id","description":"World entity ID of the operator"}},"type":"object","required":["participant_call_sid","conference_sid","mode","operator_entity_id"],"title":"JoinCallResponse","description":"Confirmation of operator joining a call's conference."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}} ``` ## Remove operator from active call > Remove operator from an active call's Twilio Conference. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"LeaveCallRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"}},"type":"object","required":["call_sid"],"title":"LeaveCallRequest","description":"Request to remove operator from an active call."},"LeaveCallResponse":{"properties":{"success":{"type":"boolean","title":"Success"}},"type":"object","required":["success"],"title":"LeaveCallResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}} ``` ## Generate browser audio access token > Generate a Twilio AccessToken with VoiceGrant for browser-based operator audio. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AccessTokenRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"}},"type":"object","required":["call_sid"],"title":"AccessTokenRequest","description":"Request to generate a Twilio AccessToken for browser-based audio."},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Browser audio not configured or voice agent unavailable."}}}}}} ``` ## Toggle operator listen/takeover mode > Switch between listen mode and takeover mode. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SwitchModeRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"participant_call_sid":{"type":"string","maxLength":64,"title":"Participant Call Sid","default":""},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["call_sid","mode"],"title":"SwitchModeRequest","description":"Request to toggle operator mode on an active call."},"SwitchModeResponse":{"properties":{"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","description":"New operator mode"}},"type":"object","required":["mode"],"title":"SwitchModeResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}} ``` ## Send text guidance to agent during call > Inject operator guidance into an active call. The agent incorporates it into its next response. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SendGuidanceRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"}},"type":"object","required":["call_sid","message"],"title":"SendGuidanceRequest"},"SendGuidanceResponse":{"properties":{"status":{"type":"string","enum":["delivered","failed"],"title":"Status","description":"Delivery status"},"call_sid":{"type":"string","title":"Call Sid","description":"Call SID the guidance was sent to"}},"type":"object","required":["status","call_sid"],"title":"SendGuidanceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Voice agent service unavailable."}}}}}} ``` ## Record operator intervention wrap-up > Persist the outcome and notes from an operator's call intervention. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"WrapUpRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"outcome":{"type":"string","enum":["resolved","escalated","transferred"],"title":"Outcome"},"notes":{"type":"string","maxLength":2000,"title":"Notes","default":""}},"type":"object","required":["call_sid","outcome"],"title":"WrapUpRequest","description":"Request to record operator intervention wrap-up."},"WrapUpResponse":{"properties":{"success":{"type":"boolean","title":"Success"}},"type":"object","required":["success"],"title":"WrapUpResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## List operators > List all operator entities for a workspace. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"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]"},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/operators":{"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"}}}}}}}}} ``` ## Register an operator > Create an operator entity with profile and initial offline status. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateOperatorRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"email":{"type":"string","format":"email","title":"Email"},"type":{"type":"string","enum":["clinical","administrative","crisis_counselor"],"title":"Type","default":"clinical"},"skills":{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":50,"title":"Skills"},"connection_method":{"type":"string","enum":["browser","phone"],"title":"Connection Method","default":"browser"},"phone_number":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"role":{"type":"string","enum":["operator","supervisor","admin"],"title":"Role","default":"operator"}},"type":"object","required":["name","email"],"title":"CreateOperatorRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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 an operator > Get operator entity with computed state (profile, availability, performance). ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}} ``` ## Update an operator > Update operator profile fields or status. Each change writes a world event. ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdateOperatorRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Type"},"skills":{"anyOf":[{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":50},{"type":"null"}],"title":"Skills"},"connection_method":{"anyOf":[{"type":"string","enum":["browser","phone"]},{"type":"null"}],"title":"Connection Method"},"phone_number":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"role":{"anyOf":[{"type":"string","enum":["operator","supervisor","admin"]},{"type":"null"}],"title":"Role"},"status":{"anyOf":[{"type":"string","enum":["online","busy","offline"]},{"type":"null"}],"title":"Status"}},"type":"object","title":"UpdateOperatorRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/operators/{operator_id}":{"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"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.amigo.ai/api-reference/readme/platform/operators.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.