# Conversations

## GET /v1/{workspace\_id}/conversations

> List all conversations (voice + text)

```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":{"ConversationListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__conversations__ConversationSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","has_more"],"title":"ConversationListResponse"},"src__routes__conversations__ConversationSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"channel_kind":{"type":"string","enum":["voice","sms","whatsapp","web","email"],"title":"Channel Kind"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed"],"title":"Status"},"lifecycle":{"type":"string","enum":["active","dormant","closed"],"title":"Lifecycle"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"escalation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Status"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"}},"type":"object","required":["id","channel_kind","status","lifecycle","created_at","updated_at"],"title":"ConversationSummary"},"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}/conversations":{"get":{"tags":["conversations"],"summary":"List all conversations (voice + text)","operationId":"list_conversations_v1__workspace_id__conversations_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"channel_kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["voice","sms","whatsapp","web","email"],"type":"string"},{"type":"null"}],"description":"Filter by channel","title":"Channel Kind"},"description":"Filter by channel"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["active","closed","completed","in-progress","failed"],"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/conversations

> Create a new text conversation

```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":{"CreateConversationRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"}},"type":"object","required":["service_id"],"title":"CreateConversationRequest"},"ConversationDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"channel_kind":{"type":"string","enum":["voice","sms","whatsapp","web","email"],"title":"Channel Kind"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed"],"title":"Status"},"lifecycle":{"type":"string","enum":["active","dormant","closed"],"title":"Lifecycle"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"escalation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Status"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"turns":{"items":{"$ref":"#/components/schemas/ConversationTurn"},"type":"array","title":"Turns","default":[]},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"voice":{"anyOf":[{"$ref":"#/components/schemas/VoiceDetail"},{"type":"null"}]}},"type":"object","required":["id","channel_kind","status","lifecycle","created_at","updated_at"],"title":"ConversationDetail"},"ConversationTurn":{"properties":{"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"VoiceDetail":{"properties":{"recording_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recording Path"},"twilio_recording_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twilio Recording Sid"},"twilio_recording_duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Twilio Recording Duration"},"has_recording":{"type":"boolean","title":"Has Recording","default":false},"verified_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified Transcript"},"transcript_accuracy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Transcript Accuracy"},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Emotional Summary"},"barge_in_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Barge In Events","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"participants":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Participants","default":[]},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"call_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Call Analysis"},"forwarding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Forwarding"},"escalation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Escalation"},"safety":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety"},"quality_breakdown":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quality Breakdown"},"risk_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Risk Summary"},"latency_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Summary"},"conversation_metrics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Metrics"},"tool_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"},"operator_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Operator Summary"}},"type":"object","title":"VoiceDetail"},"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}/conversations":{"post":{"tags":["conversations"],"summary":"Create a new text conversation","operationId":"create_conversation_v1__workspace_id__conversations_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"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 /v1/{workspace\_id}/conversations/{conversation\_id}

> Get conversation detail (voice or text)

```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":{"ConversationDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"channel_kind":{"type":"string","enum":["voice","sms","whatsapp","web","email"],"title":"Channel Kind"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed"],"title":"Status"},"lifecycle":{"type":"string","enum":["active","dormant","closed"],"title":"Lifecycle"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"escalation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Status"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"turns":{"items":{"$ref":"#/components/schemas/ConversationTurn"},"type":"array","title":"Turns","default":[]},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"voice":{"anyOf":[{"$ref":"#/components/schemas/VoiceDetail"},{"type":"null"}]}},"type":"object","required":["id","channel_kind","status","lifecycle","created_at","updated_at"],"title":"ConversationDetail"},"ConversationTurn":{"properties":{"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"VoiceDetail":{"properties":{"recording_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recording Path"},"twilio_recording_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twilio Recording Sid"},"twilio_recording_duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Twilio Recording Duration"},"has_recording":{"type":"boolean","title":"Has Recording","default":false},"verified_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified Transcript"},"transcript_accuracy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Transcript Accuracy"},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Emotional Summary"},"barge_in_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Barge In Events","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"participants":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Participants","default":[]},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"call_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Call Analysis"},"forwarding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Forwarding"},"escalation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Escalation"},"safety":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety"},"quality_breakdown":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quality Breakdown"},"risk_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Risk Summary"},"latency_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Summary"},"conversation_metrics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Metrics"},"tool_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"},"operator_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Operator Summary"}},"type":"object","title":"VoiceDetail"},"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}/conversations/{conversation_id}":{"get":{"tags":["conversations"],"summary":"Get conversation detail (voice or text)","operationId":"get_conversation_v1__workspace_id__conversations__conversation_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/conversations/{conversation\_id}

> Close a conversation

```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":{"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}/conversations/{conversation_id}":{"delete":{"tags":["conversations"],"summary":"Close a conversation","operationId":"close_conversation_v1__workspace_id__conversations__conversation_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Send a message and get the agent's response

> Send a user message and receive the agent's response. Set \`Accept: text/event-stream\` to receive an SSE stream of typed \`TurnStreamEvent\` frames (token, tool\_call\_started, tool\_call\_completed, thinking, message, done, error) instead of the synchronous JSON response. For new integrations prefer \`POST /turns/stream\`, which is always SSE.

```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":{"TurnRequest":{"properties":{"message":{"type":"string","maxLength":10000,"title":"Message","default":""},"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","maxItems":20},{"type":"null"}],"title":"Content"},"media_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Media Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"context":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Context","description":"Injected into the agent's prompt as caller/patient context for this turn."},"viewport_width":{"anyOf":[{"type":"integer","maximum":500,"minimum":20},{"type":"null"}],"title":"Viewport Width"},"viewport_height":{"anyOf":[{"type":"integer","maximum":500,"minimum":5},{"type":"null"}],"title":"Viewport Height"}},"type":"object","title":"TurnRequest"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"TurnResponse":{"properties":{"turn_id":{"type":"string","title":"Turn Id"},"input":{"$ref":"#/components/schemas/ConversationTurn"},"output":{"items":{"$ref":"#/components/schemas/ConversationTurn"},"type":"array","title":"Output"},"tool_calls":{"items":{"$ref":"#/components/schemas/ConversationToolCallDetail"},"type":"array","title":"Tool Calls","default":[]},"conversation":{"$ref":"#/components/schemas/TurnConversationSnapshot"}},"type":"object","required":["turn_id","input","output","conversation"],"title":"TurnResponse"},"ConversationTurn":{"properties":{"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ConversationToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"type":"string","title":"Call Id"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"result":{"type":"string","title":"Result","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"duration_ms":{"anyOf":[{"type":"number","maximum":3600000,"minimum":0},{"type":"null"}],"title":"Duration Ms","description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Omitted (null) on legacy turns that did not capture timing."}},"type":"object","required":["tool_name","call_id"],"title":"ConversationToolCallDetail"},"TurnConversationSnapshot":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed"],"title":"Status"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","status","updated_at"],"title":"TurnConversationSnapshot"},"TurnStreamEvent":{"discriminator":{"mapping":{"done":"#/components/schemas/TurnDoneEvent","error":"#/components/schemas/TurnErrorEvent","message":"#/components/schemas/TurnMessageEvent","thinking":"#/components/schemas/TurnThinkingEvent","token":"#/components/schemas/TurnTokenEvent","tool_call_completed":"#/components/schemas/TurnToolCallCompletedEvent","tool_call_started":"#/components/schemas/TurnToolCallStartedEvent"},"propertyName":"event"},"oneOf":[{"$ref":"#/components/schemas/TurnTokenEvent"},{"$ref":"#/components/schemas/TurnToolCallStartedEvent"},{"$ref":"#/components/schemas/TurnToolCallCompletedEvent"},{"$ref":"#/components/schemas/TurnThinkingEvent"},{"$ref":"#/components/schemas/TurnMessageEvent"},{"$ref":"#/components/schemas/TurnDoneEvent"},{"$ref":"#/components/schemas/TurnErrorEvent"}]},"TurnTokenEvent":{"properties":{"event":{"const":"token","default":"token","title":"Event","type":"string"},"text":{"title":"Text","type":"string"}},"required":["text"],"title":"TurnTokenEvent","type":"object"},"TurnToolCallStartedEvent":{"properties":{"event":{"const":"tool_call_started","default":"tool_call_started","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"title":"Input","type":"string"}},"required":["tool_name","call_id","input"],"title":"TurnToolCallStartedEvent","type":"object"},"TurnToolCallCompletedEvent":{"properties":{"event":{"const":"tool_call_completed","default":"tool_call_completed","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"result":{"title":"Result","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"maximum":3600000,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Null when the upstream did not report timing (legacy/test paths).","title":"Duration Ms"}},"required":["tool_name","call_id","result","succeeded"],"title":"TurnToolCallCompletedEvent","type":"object"},"TurnThinkingEvent":{"properties":{"event":{"const":"thinking","default":"thinking","title":"Event","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"title":"Tier Name","type":"string"}},"required":["tier","tier_name"],"title":"TurnThinkingEvent","type":"object"},"TurnMessageEvent":{"properties":{"event":{"const":"message","default":"message","title":"Event","type":"string"},"role":{"title":"Role","type":"string"},"text":{"title":"Text","type":"string"}},"required":["role","text"],"title":"TurnMessageEvent","type":"object"},"TurnDoneEvent":{"properties":{"event":{"const":"done","default":"done","title":"Event","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"status":{"title":"Status","type":"string"},"turn_count":{"title":"Turn Count","type":"integer"}},"required":["conversation_id","status","turn_count"],"title":"TurnDoneEvent","type":"object"},"TurnErrorEvent":{"description":"Terminal error frame on the turn stream.\n\nCarries a stable ``code`` so SDK consumers can branch deterministically\nwithout parsing free-form ``message`` text. ``retryable`` tells the\nconsumer whether issuing the same turn again is likely to succeed.\n``status_code`` is the upstream HTTP status when the error originated\nfrom a downstream service (agent-engine), and is otherwise omitted.","properties":{"event":{"const":"error","default":"error","title":"Event","type":"string"},"message":{"title":"Message","type":"string"},"code":{"default":"unknown","enum":["upstream_error","stream_interrupted","client_error","unknown"],"title":"Code","type":"string"},"retryable":{"default":false,"title":"Retryable","type":"boolean"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Status Code"}},"required":["message"],"title":"TurnErrorEvent","type":"object"},"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}/conversations/{conversation_id}/turns":{"post":{"tags":["conversations"],"summary":"Send a message and get the agent's response","description":"Send a user message and receive the agent's response. Set `Accept: text/event-stream` to receive an SSE stream of typed `TurnStreamEvent` frames (token, tool_call_started, tool_call_completed, thinking, message, done, error) instead of the synchronous JSON response. For new integrations prefer `POST /turns/stream`, which is always SSE.","operationId":"create_turn_v1__workspace_id__conversations__conversation_id__turns_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"include_tool_calls","in":"query","required":false,"schema":{"type":"boolean","description":"Include tool call details in response","default":false,"title":"Include Tool Calls"},"description":"Include tool call details in response"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnResponse"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/TurnStreamEvent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Send a message and receive a streamed agent response

> Streaming variant of \`POST /turns\`. Always returns \`text/event-stream\` regardless of the \`Accept\` header — no JSON fallback. Each frame is a \`TurnStreamEvent\` discriminated by the \`event\` field (token, tool\_call\_started, tool\_call\_completed, thinking, message, done, error). Use this endpoint for new integrations; the \`Accept\`-sniffing variant remains for backward compatibility.

```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":{"TurnRequest":{"properties":{"message":{"type":"string","maxLength":10000,"title":"Message","default":""},"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","maxItems":20},{"type":"null"}],"title":"Content"},"media_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Media Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"context":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Context","description":"Injected into the agent's prompt as caller/patient context for this turn."},"viewport_width":{"anyOf":[{"type":"integer","maximum":500,"minimum":20},{"type":"null"}],"title":"Viewport Width"},"viewport_height":{"anyOf":[{"type":"integer","maximum":500,"minimum":5},{"type":"null"}],"title":"Viewport Height"}},"type":"object","title":"TurnRequest"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"TurnStreamEvent":{"discriminator":{"mapping":{"done":"#/components/schemas/TurnDoneEvent","error":"#/components/schemas/TurnErrorEvent","message":"#/components/schemas/TurnMessageEvent","thinking":"#/components/schemas/TurnThinkingEvent","token":"#/components/schemas/TurnTokenEvent","tool_call_completed":"#/components/schemas/TurnToolCallCompletedEvent","tool_call_started":"#/components/schemas/TurnToolCallStartedEvent"},"propertyName":"event"},"oneOf":[{"$ref":"#/components/schemas/TurnTokenEvent"},{"$ref":"#/components/schemas/TurnToolCallStartedEvent"},{"$ref":"#/components/schemas/TurnToolCallCompletedEvent"},{"$ref":"#/components/schemas/TurnThinkingEvent"},{"$ref":"#/components/schemas/TurnMessageEvent"},{"$ref":"#/components/schemas/TurnDoneEvent"},{"$ref":"#/components/schemas/TurnErrorEvent"}]},"TurnTokenEvent":{"properties":{"event":{"const":"token","default":"token","title":"Event","type":"string"},"text":{"title":"Text","type":"string"}},"required":["text"],"title":"TurnTokenEvent","type":"object"},"TurnToolCallStartedEvent":{"properties":{"event":{"const":"tool_call_started","default":"tool_call_started","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"title":"Input","type":"string"}},"required":["tool_name","call_id","input"],"title":"TurnToolCallStartedEvent","type":"object"},"TurnToolCallCompletedEvent":{"properties":{"event":{"const":"tool_call_completed","default":"tool_call_completed","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"result":{"title":"Result","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"maximum":3600000,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Null when the upstream did not report timing (legacy/test paths).","title":"Duration Ms"}},"required":["tool_name","call_id","result","succeeded"],"title":"TurnToolCallCompletedEvent","type":"object"},"TurnThinkingEvent":{"properties":{"event":{"const":"thinking","default":"thinking","title":"Event","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"title":"Tier Name","type":"string"}},"required":["tier","tier_name"],"title":"TurnThinkingEvent","type":"object"},"TurnMessageEvent":{"properties":{"event":{"const":"message","default":"message","title":"Event","type":"string"},"role":{"title":"Role","type":"string"},"text":{"title":"Text","type":"string"}},"required":["role","text"],"title":"TurnMessageEvent","type":"object"},"TurnDoneEvent":{"properties":{"event":{"const":"done","default":"done","title":"Event","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"status":{"title":"Status","type":"string"},"turn_count":{"title":"Turn Count","type":"integer"}},"required":["conversation_id","status","turn_count"],"title":"TurnDoneEvent","type":"object"},"TurnErrorEvent":{"description":"Terminal error frame on the turn stream.\n\nCarries a stable ``code`` so SDK consumers can branch deterministically\nwithout parsing free-form ``message`` text. ``retryable`` tells the\nconsumer whether issuing the same turn again is likely to succeed.\n``status_code`` is the upstream HTTP status when the error originated\nfrom a downstream service (agent-engine), and is otherwise omitted.","properties":{"event":{"const":"error","default":"error","title":"Event","type":"string"},"message":{"title":"Message","type":"string"},"code":{"default":"unknown","enum":["upstream_error","stream_interrupted","client_error","unknown"],"title":"Code","type":"string"},"retryable":{"default":false,"title":"Retryable","type":"boolean"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Status Code"}},"required":["message"],"title":"TurnErrorEvent","type":"object"}}},"paths":{"/v1/{workspace_id}/conversations/{conversation_id}/turns/stream":{"post":{"tags":["conversations"],"summary":"Send a message and receive a streamed agent response","description":"Streaming variant of `POST /turns`. Always returns `text/event-stream` regardless of the `Accept` header — no JSON fallback. Each frame is a `TurnStreamEvent` discriminated by the `event` field (token, tool_call_started, tool_call_completed, thinking, message, done, error). Use this endpoint for new integrations; the `Accept`-sniffing variant remains for backward compatibility.","operationId":"create_turn_stream_v1__workspace_id__conversations__conversation_id__turns_stream_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"include_tool_calls","in":"query","required":false,"schema":{"type":"boolean","description":"Include tool_call_started / tool_call_completed frames in the stream","default":false,"title":"Include Tool Calls"},"description":"Include tool_call_started / tool_call_completed frames in the stream"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnRequest"}}}},"responses":{"200":{"description":"SSE stream of TurnStreamEvent frames","content":{"application/json":{"schema":{}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/TurnStreamEvent"}}}},"404":{"description":"Conversation or service not found"},"409":{"description":"Conversation is closed"},"422":{"description":"Conversation is missing or has corrupt service binding"},"503":{"description":"Agent service unavailable"}}}}}}
```


---

# 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/conversations.md?ask=<question>
```

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.