# 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"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"status":{"type":"string","title":"Status"},"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"},"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"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds"},"operator_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Entity Id"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"}},"type":"object","required":["call_entity_id","call_sid","escalation_id","status","trigger","trigger_source","concept","operator_type","regulatory_basis","immediate","risk_score","requested_at","connected_at","wait_seconds","operator_entity_id","caller_id","direction","phone_number","started_at"],"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"}}}}}}}}}
```

## 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"},"status":{"type":"string","title":"Status"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"}},"type":"object","required":["operator_id","name","status","total_escalations_handled","avg_handle_time_seconds","last_call_at"],"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"}}}}}}}}}
```

## 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"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"status":{"type":"string","title":"Status"},"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"},"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"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds"},"operator_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Entity Id"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"}},"type":"object","required":["call_entity_id","call_sid","escalation_id","status","trigger","trigger_source","concept","operator_type","regulatory_basis","immediate","risk_score","requested_at","connected_at","wait_seconds","operator_entity_id","caller_id","direction","phone_number","started_at"],"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":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"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":"period","in":"query","required":false,"schema":{"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":{"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"}}}}}}}}}
```

## 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":"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"},"caller_id":{"type":"string","title":"Caller Id","default":""},"service_id":{"type":"string","title":"Service Id","default":""},"direction":{"type":"string","title":"Direction","default":"inbound"},"priority_score":{"type":"number","maximum":1,"minimum":0,"title":"Priority Score"},"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"},"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."}}},"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."}}}}}}
```

## 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":"operator_id","in":"path","required":true,"schema":{"type":"string","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"},"conference_sid":{"type":"string","title":"Conference Sid"},"mode":{"type":"string","title":"Mode"},"operator_entity_id":{"type":"string","title":"Operator Entity Id"}},"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":"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":"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":"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","title":"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":"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","title":"Status"},"call_sid":{"type":"string","title":"Call Sid"}},"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":"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":"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"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"},"connection_method":{"type":"string","title":"Connection Method"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","email","type","skills","connection_method","phone_number","role","status","last_status_change","active_call_sid","total_escalations_handled","avg_handle_time_seconds","last_call_at","created_at","updated_at"],"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":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"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"},"type":"array","title":"Skills"},"connection_method":{"type":"string","enum":["browser","phone"],"title":"Connection Method","default":"browser"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"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},"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"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"},"connection_method":{"type":"string","title":"Connection Method"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","email","type","skills","connection_method","phone_number","role","status","last_status_change","active_call_sid","total_escalations_handled","avg_handle_time_seconds","last_call_at","created_at","updated_at"],"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"}}}}}}}}}
```

## 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"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"},"connection_method":{"type":"string","title":"Connection Method"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","email","type","skills","connection_method","phone_number","role","status","last_status_change","active_call_sid","total_escalations_handled","avg_handle_time_seconds","last_call_at","created_at","updated_at"],"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":"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"},"type":"array"},{"type":"null"}],"title":"Skills"},"connection_method":{"anyOf":[{"type":"string","enum":["browser","phone"]},{"type":"null"}],"title":"Connection Method"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"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},"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"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"},"connection_method":{"type":"string","title":"Connection Method"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","email","type","skills","connection_method","phone_number","role","status","last_status_change","active_call_sid","total_escalations_handled","avg_handle_time_seconds","last_call_at","created_at","updated_at"],"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":"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"}}}}}}}}}
```