Conversations

List all conversations (voice + text)

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

channel_kindany ofOptional

Filter by channel

string · enumOptionalPossible values:

or

nullOptional

statusany ofOptional

Filter by status

string · enumOptionalPossible values:

or

nullOptional

limitinteger · min: 1 · max: 100OptionalDefault: 20

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

totalintegerRequired

has_morebooleanRequired

422

Validation Error

application/json

get

/v1/{workspace_id}/conversations

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/conversations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "channel_kind": "voice",
      "status": "active",
      "lifecycle": "active",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "text",
      "turn_count": 0,
      "duration_seconds": 1,
      "created_at": "text",
      "updated_at": "text",
      "call_sid": "text",
      "caller_id": "text",
      "phone_number": "text",
      "quality_score": 1,
      "has_recording": true,
      "completion_reason": "text",
      "escalation_status": "text",
      "final_state": "text",
      "source": "text"
    }
  ],
  "total": 1,
  "has_more": true
}

Create a new text conversation

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

service_idstring · uuidRequired

entity_idany ofOptional

string · uuidOptional

or

nullOptional

start_modestring · enumOptionalDefault: user_firstPossible values:

contextany ofOptional

Injected into the agent's prompt as caller/patient context for this conversation.

string · max: 5000Optional

or

nullOptional

viewport_widthany ofOptional

integer · min: 20 · max: 500Optional

or

nullOptional

viewport_heightany ofOptional

integer · min: 5 · max: 500Optional

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/v1/{workspace_id}/conversations

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/conversations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 186

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_mode": "user_first",
  "context": "text",
  "viewport_width": 1,
  "viewport_height": 1
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channel_kind": "voice",
  "status": "active",
  "lifecycle": "active",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "text",
  "turn_count": 0,
  "duration_seconds": 1,
  "created_at": "text",
  "updated_at": "text",
  "call_sid": "text",
  "caller_id": "text",
  "phone_number": "text",
  "quality_score": 1,
  "has_recording": true,
  "completion_reason": "text",
  "escalation_status": "text",
  "final_state": "text",
  "source": "text",
  "turns": [
    {
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "content": [
        {
          "type": "text",
          "text": "text",
          "url": "text",
          "media_type": "text",
          "provider_id": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ]
    }
  ],
  "plan": "text",
  "voice": {
    "recording_path": "text",
    "twilio_recording_sid": "text",
    "twilio_recording_duration": 1,
    "has_recording": false,
    "verified_transcript": "text",
    "transcript_accuracy": 1,
    "emotional_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "barge_in_events": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "participants": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "call_analysis": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "forwarding": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "escalation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "safety": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "quality_breakdown": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "risk_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "latency_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "conversation_metrics": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "tool_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "safety_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "operator_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Get conversation detail (voice or text)

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

channel_kindstring · enumRequiredPossible values:

statusstring · enumRequiredPossible values:

lifecyclestring · enumRequiredPossible values:

entity_idany ofOptional

string · uuidOptional

or

nullOptional

service_idany ofOptional

string · uuidOptional

or

nullOptional

directionany ofOptional

stringOptional

or

nullOptional

turn_countintegerOptionalDefault: 0

duration_secondsany ofOptional

numberOptional

or

nullOptional

created_atstringRequired

updated_atstringRequired

call_sidany ofOptional

stringOptional

or

nullOptional

caller_idany ofOptional

stringOptional

or

nullOptional

phone_numberany ofOptional

stringOptional

or

nullOptional

quality_scoreany ofOptional

numberOptional

or

nullOptional

has_recordingany ofOptional

booleanOptional

or

nullOptional

completion_reasonany ofOptional

stringOptional

or

nullOptional

escalation_statusany ofOptional

stringOptional

or

nullOptional

final_stateany ofOptional

stringOptional

or

nullOptional

sourceany ofOptional

stringOptional

or

nullOptional

planany ofOptional

stringOptional

or

nullOptional

voiceany ofOptional

or

nullOptional

422

Validation Error

application/json

get

/v1/{workspace_id}/conversations/{conversation_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/conversations/{conversation_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channel_kind": "voice",
  "status": "active",
  "lifecycle": "active",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "text",
  "turn_count": 0,
  "duration_seconds": 1,
  "created_at": "text",
  "updated_at": "text",
  "call_sid": "text",
  "caller_id": "text",
  "phone_number": "text",
  "quality_score": 1,
  "has_recording": true,
  "completion_reason": "text",
  "escalation_status": "text",
  "final_state": "text",
  "source": "text",
  "turns": [
    {
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "content": [
        {
          "type": "text",
          "text": "text",
          "url": "text",
          "media_type": "text",
          "provider_id": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ]
    }
  ],
  "plan": "text",
  "voice": {
    "recording_path": "text",
    "twilio_recording_sid": "text",
    "twilio_recording_duration": 1,
    "has_recording": false,
    "verified_transcript": "text",
    "transcript_accuracy": 1,
    "emotional_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "barge_in_events": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "participants": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "call_analysis": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "forwarding": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "escalation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "safety": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "quality_breakdown": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "risk_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "latency_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "conversation_metrics": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "tool_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "safety_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "operator_summary": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Close a conversation

delete

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Responses

204

Successful Response

422

Validation Error

application/json

delete

/v1/{workspace_id}/conversations/{conversation_id}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/conversations/{conversation_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Send a message and get the agent's response

post

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.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Query parameters

include_tool_callsbooleanOptional

Include tool call details in response

Default: false

Body

application/json

messagestring · min: 1 · max: 10000Required

contentany ofOptional

or

nullOptional

media_urlany ofOptional

string · max: 2048Optional

or

nullOptional

media_typeany ofOptional

string · max: 128Optional

or

nullOptional

contextany ofOptional

Injected into the agent's prompt as caller/patient context for this turn.

string · max: 5000Optional

or

nullOptional

viewport_widthany ofOptional

integer · min: 20 · max: 500Optional

or

nullOptional

viewport_heightany ofOptional

integer · min: 5 · max: 500Optional

or

nullOptional

Responses

200

Successful Response

application/jsontext/event-stream

turn_idstringRequired

422

Validation Error

application/json

post

/v1/{workspace_id}/conversations/{conversation_id}/turns

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/conversations/{conversation_id}/turns HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "message": "text",
  "content": [
    {
      "type": "text",
      "text": "text",
      "url": "text",
      "media_type": "text",
      "provider_id": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "media_url": "text",
  "media_type": "text",
  "context": "text",
  "viewport_width": 1,
  "viewport_height": 1
}

{
  "turn_id": "text",
  "input": {
    "role": "agent",
    "text": "text",
    "timestamp": "text",
    "content": [
      {
        "type": "text",
        "text": "text",
        "url": "text",
        "media_type": "text",
        "provider_id": "text",
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ]
  },
  "output": [
    {
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "content": [
        {
          "type": "text",
          "text": "text",
          "url": "text",
          "media_type": "text",
          "provider_id": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ]
    }
  ],
  "tool_calls": [
    {
      "tool_name": "text",
      "call_id": "text",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "result": "",
      "succeeded": true,
      "duration_ms": 1
    }
  ],
  "conversation": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "active",
    "turn_count": 0,
    "updated_at": "text"
  }
}

Send a message and receive a streamed agent response

post

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.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Query parameters

include_tool_callsbooleanOptional

Include tool_call_started / tool_call_completed frames in the stream

Default: false

Body

application/json

messagestring · min: 1 · max: 10000Required

contentany ofOptional

or

nullOptional

media_urlany ofOptional

string · max: 2048Optional

or

nullOptional

media_typeany ofOptional

string · max: 128Optional

or

nullOptional

contextany ofOptional

Injected into the agent's prompt as caller/patient context for this turn.

string · max: 5000Optional

or

nullOptional

viewport_widthany ofOptional

integer · min: 20 · max: 500Optional

or

nullOptional

viewport_heightany ofOptional

integer · min: 5 · max: 500Optional

or

nullOptional

Responses

200

SSE stream of TurnStreamEvent frames

application/jsontext/event-stream

anyOptional

404

Conversation or service not found

409

Conversation is closed

422

Conversation is missing or has corrupt service binding

503

Agent service unavailable

post

/v1/{workspace_id}/conversations/{conversation_id}/turns/stream

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/conversations/{conversation_id}/turns/stream HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "message": "text",
  "content": [
    {
      "type": "text",
      "text": "text",
      "url": "text",
      "media_type": "text",
      "provider_id": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "media_url": "text",
  "media_type": "text",
  "context": "text",
  "viewport_width": 1,
  "viewport_height": 1
}

No content