For the complete documentation index, see llms.txt. This page is also available as Markdown.

Conversations

Create or start a conversation (web inbound, or outbound on a channel)

post
Authorizations
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
service_idstring · uuidRequired
entity_idstring · uuid · nullableOptional
channelstring · enumOptional

HSM execution channel type.

Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.

Default: webPossible values:
recipientstring · min: 2 · max: 16 · nullableOptional

Destination address for an outbound conversation (E.164 for sms/imessage). Required for non-web.

use_case_idstring · uuid · nullableOptional

Channel-manager use case the outbound conversation is sent through. Required for non-web; channel-manager resolves the sender (FROM) from it (never caller-supplied). Must be owned by this workspace.

instructionstring · max: 10000 · nullableOptional

Optional context steering what the agent opens with on an outbound conversation.

force_newbooleanOptional

Outbound thread-keyed channels (sms/imessage) only: close any existing ACTIVE conversation on the computed provider thread (recipient + use case) before dispatching, so the opener materializes a brand-new conversation instead of continuing the old thread. Rejected with 422 on channel=web — every web create already starts a new conversation, so force_new is meaningless there.

Default: false
Responses
201

Successful Response

application/json
idstring · uuidRequired
channel_kindstring · enumRequired

HSM execution channel type.

Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.

Possible values:
statusstring · enumRequiredPossible values:
lifecyclestring · enumRequiredPossible values:
entity_idstring · uuid · nullableOptional
service_idstring · uuid · nullableOptional
directionstring · nullableOptional
turn_countintegerOptionalDefault: 0
duration_secondsnumber · nullableOptional
created_atstringRequired
updated_atstringRequired
call_sidstring · nullableOptional
caller_idstring · nullableOptional
phone_numberstring · nullableOptional
quality_scorenumber · nullableOptional
has_recordingboolean · nullableOptional
completion_reasonstring · nullableOptional
escalation_statusstring · nullableOptional
final_statestring · nullableOptional
sourcestring · nullableOptional
planstring · nullableOptional
post/v1/{workspace_id}/conversations
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: 231

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "web",
  "recipient": "text",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "instruction": "text",
  "force_new": false
}
{
  "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": [
    {
      "turn_id": "123e4567-e89b-12d3-a456-426614174000",
      "turn_index": 1,
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "channel": "voice",
      "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,
          "error_message": "text"
        }
      ],
      "artifacts": [
        {
          "type": "text",
          "schema_version": "text",
          "payload": "[Circular Reference]"
        }
      ],
      "selected_action_description": "text",
      "state_transitions": [
        {
          "from": "text",
          "to": "text"
        }
      ],
      "available_actions": [
        {
          "description": "text"
        }
      ]
    }
  ],
  "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"
    }
  }
}

Switch a conversation to another channel

post

Move an active conversation onto a different channel (sms/imessage today). The durable conversation id is preserved — the same conversation continues; only its routing changes. Optionally dispatch a first agent turn on the new channel.

Authorizations
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
Body
channelstring · enumRequired

Target channel to move the conversation to (sms or imessage).

Possible values:
recipientstring · min: 2 · max: 16 · nullableOptional

Recipient address on the new channel (E.164). Required for sms/imessage.

use_case_idstring · uuid · nullableOptional

Channel-manager use case for the new channel (resolves the sender). Required for sms/imessage.

reasonstring · min: 1 · max: 256Required

Why the conversation is being moved (e.g. escalation, customer_request).

dispatch_openerbooleanOptional

If true, immediately drive one agent turn on the new channel (e.g. 'I'll text you now').

Default: false
instructionstring · max: 10000 · nullableOptional

Optional context steering the opener when dispatch_opener=true.

Responses
200

Successful Response

application/json
idstring · uuidRequired
channel_kindstring · enumRequired

HSM execution channel type.

Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.

Possible values:
statusstring · enumRequiredPossible values:
lifecyclestring · enumRequiredPossible values:
entity_idstring · uuid · nullableOptional
service_idstring · uuid · nullableOptional
directionstring · nullableOptional
turn_countintegerOptionalDefault: 0
duration_secondsnumber · nullableOptional
created_atstringRequired
updated_atstringRequired
call_sidstring · nullableOptional
caller_idstring · nullableOptional
phone_numberstring · nullableOptional
quality_scorenumber · nullableOptional
has_recordingboolean · nullableOptional
completion_reasonstring · nullableOptional
escalation_statusstring · nullableOptional
final_statestring · nullableOptional
sourcestring · nullableOptional
planstring · nullableOptional
post/v1/{workspace_id}/conversations/{conversation_id}/channel
POST /v1/{workspace_id}/conversations/{conversation_id}/channel HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 152

{
  "channel": "voice",
  "recipient": "text",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "reason": "text",
  "dispatch_opener": false,
  "instruction": "text"
}
{
  "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": [
    {
      "turn_id": "123e4567-e89b-12d3-a456-426614174000",
      "turn_index": 1,
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "channel": "voice",
      "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,
          "error_message": "text"
        }
      ],
      "artifacts": [
        {
          "type": "text",
          "schema_version": "text",
          "payload": "[Circular Reference]"
        }
      ],
      "selected_action_description": "text",
      "state_transitions": [
        {
          "from": "text",
          "to": "text"
        }
      ],
      "available_actions": [
        {
          "description": "text"
        }
      ]
    }
  ],
  "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
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 per-turn tool_calls[] in the returned turns. Off by default so the payload stays small and (potentially PHI-bearing) tool output is opt-in, matching POST /turns?include_tool_calls=true.

Default: false
Responses
200

Successful Response

application/json
idstring · uuidRequired
channel_kindstring · enumRequired

HSM execution channel type.

Determines how the HSM engine communicates with end users. Each kind maps to one or more providers.

Possible values:
statusstring · enumRequiredPossible values:
lifecyclestring · enumRequiredPossible values:
entity_idstring · uuid · nullableOptional
service_idstring · uuid · nullableOptional
directionstring · nullableOptional
turn_countintegerOptionalDefault: 0
duration_secondsnumber · nullableOptional
created_atstringRequired
updated_atstringRequired
call_sidstring · nullableOptional
caller_idstring · nullableOptional
phone_numberstring · nullableOptional
quality_scorenumber · nullableOptional
has_recordingboolean · nullableOptional
completion_reasonstring · nullableOptional
escalation_statusstring · nullableOptional
final_statestring · nullableOptional
sourcestring · nullableOptional
planstring · nullableOptional
get/v1/{workspace_id}/conversations/{conversation_id}
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": [
    {
      "turn_id": "123e4567-e89b-12d3-a456-426614174000",
      "turn_index": 1,
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "channel": "voice",
      "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,
          "error_message": "text"
        }
      ],
      "artifacts": [
        {
          "type": "text",
          "schema_version": "text",
          "payload": "[Circular Reference]"
        }
      ],
      "selected_action_description": "text",
      "state_transitions": [
        {
          "from": "text",
          "to": "text"
        }
      ],
      "available_actions": [
        {
          "description": "text"
        }
      ]
    }
  ],
  "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
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

No content

delete/v1/{workspace_id}/conversations/{conversation_id}
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
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
pollbooleanOptional

Poll for a background result without sending a user message. Protocol v2 claims at most one ready answer and returns an opaque delivery receipt; render or durably persist the answer, then acknowledge that receipt. Returns empty output when nothing is ready. Must NOT be combined with a request-body message (422) or SSE streaming (422). Poll no more than once every ~5s per conversation.

Default: false
Header parameters
Idempotency-Keystring · uuid · nullableOptional

Stable UUID for replaying the same logical send or poll after an ambiguous failure. Reuse the same value only for that operation. Omission is backward-compatible but cannot provide client-controlled response-loss replay.

Body
messagestring · max: 10000OptionalDefault: ""
media_urlstring · max: 2048 · nullableOptional
media_typestring · max: 128 · nullableOptional
contextstring · max: 100000 · nullableOptional

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

viewport_widthinteger · min: 20 · max: 500 · nullableOptional
viewport_heightinteger · min: 5 · max: 500 · nullableOptional
wait_for_finalboolean · nullableOptional

Synchronous callers only: when a turn hands work to a background tool (background_pending), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with background_pending=false; on timeout it returns background_pending=true — resolve it later with poll=true. null (default) inherits the channel policy (web = do not wait). Ignored with poll=true (422).

suppress_fillerboolean · nullableOptional

Synchronous callers only: when a turn ends background_pending, omit the filler/acknowledgement text from output so a batch caller never mistakes the ack for the answer (output is empty; background_pending=true is the poll-later signal). null (default) inherits the channel policy. Ignored with poll=true (422).

Responses
200

Successful Response

turn_idstring · uuid · nullableRequired

Identifier of the user exchange this turn created — or, for poll=true and greeting-kickoff turns (empty message), the exchange the returned messages attach to. A background delivery keeps the originating exchange even when later user turns already exist. Deterministic: matches the turn_id on this conversation's history turns, so it can anchor durable per-turn artifacts (e.g. feedback) across page reloads. Null only when the conversation has no user exchange yet (a poll or kickoff before the first user message).

background_pendingbooleanOptional

Whether this turn's output is the final answer, or only an acknowledgement that work is still running in the background.

false (default): output is the complete agent response for this turn.

true: a tool crossed the server's blocking window and was handed to a background task, so output is NOT the final answer — the definitive assistant answer is produced later, out-of-band. Under delivery protocol v2, collect it by re-issuing POST …/turns with poll=true (a no-message, receipt-backed claim), render or durably persist the returned answer, then acknowledge its exact delivery receipt. This is the per-conversation delivery contract — see the web-integration paved path. (The workspace observer bus, GET /v1/{workspace_id}/events/stream, mirrors this activity as text.agent_message / text.tool_started / text.background_result for dashboards watching many conversations, but is not the per-chat delivery path.) A client that treats a background_pending=true turn as complete without polling and acknowledging will miss the final answer.

Default: false
delivery_protocol_versionconst: 2 · nullableOptional

Version of the durable background-delivery protocol supported by the serving agent. Clients may retry polls only after observing version 2.

post/v1/{workspace_id}/conversations/{conversation_id}/turns
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: 300

{
  "message": "",
  "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,
  "wait_for_final": true,
  "suppress_filler": true
}
{
  "turn_id": "123e4567-e89b-12d3-a456-426614174000",
  "input": {
    "turn_id": "123e4567-e89b-12d3-a456-426614174000",
    "turn_index": 1,
    "role": "agent",
    "text": "text",
    "timestamp": "text",
    "channel": "voice",
    "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,
        "error_message": "text"
      }
    ],
    "artifacts": [
      {
        "type": "text",
        "schema_version": "text",
        "payload": {
          "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
        }
      }
    ],
    "selected_action_description": "text",
    "state_transitions": [
      {
        "from": "text",
        "to": "text"
      }
    ],
    "available_actions": [
      {
        "description": "text"
      }
    ]
  },
  "output": [
    {
      "turn_id": "123e4567-e89b-12d3-a456-426614174000",
      "turn_index": 1,
      "role": "agent",
      "text": "text",
      "timestamp": "text",
      "channel": "voice",
      "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,
          "error_message": "text"
        }
      ],
      "artifacts": [
        {
          "type": "text",
          "schema_version": "text",
          "payload": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          }
        }
      ],
      "selected_action_description": "text",
      "state_transitions": [
        {
          "from": "text",
          "to": "text"
        }
      ],
      "available_actions": [
        {
          "description": "text"
        }
      ]
    }
  ],
  "tool_calls": [
    {
      "tool_name": "text",
      "call_id": "text",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "result": "",
      "succeeded": true,
      "duration_ms": 1,
      "error_message": "text"
    }
  ],
  "artifacts": [
    {
      "type": "text",
      "schema_version": "text",
      "payload": {
        "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
      }
    }
  ],
  "conversation": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "active",
    "turn_count": 0,
    "updated_at": "text",
    "context_graph_state": {
      "type": "text",
      "name": "text",
      "objective": "text",
      "actions": [
        {
          "description": "text",
          "filler_hint": "text"
        }
      ],
      "intra_state_navigation_guidelines": [
        "text"
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "exit_conditions": [
        {
          "description": "text",
          "next_state": "text",
          "filler_hint": "text"
        }
      ],
      "action_tool_call_specs": [
        {
          "tool_id": "text",
          "additional_instruction": "",
          "navigate_on_completion": false,
          "progress": {
            "deterministic": false,
            "phrases": [
              "text"
            ],
            "trigger_delay_ms": 1,
            "interval_ms": 1,
            "mode": "auto",
            "progress_class": "lookup",
            "expected_latency_ms": 1,
            "custom_phrase": "text"
          },
          "result_persistence": "accumulate",
          "delivery": "interrupt",
          "failure_delivery": "interrupt",
          "failure_delivery_by_class": {
            "ANY_ADDITIONAL_PROPERTY": "interrupt"
          },
          "execution": "blocking",
          "lifecycle": "independent",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 1
        }
      ],
      "exit_condition_tool_call_specs": [
        {
          "tool_id": "text",
          "additional_instruction": "",
          "navigate_on_completion": false,
          "progress": {
            "deterministic": false,
            "phrases": [
              "text"
            ],
            "trigger_delay_ms": 1,
            "interval_ms": 1,
            "mode": "auto",
            "progress_class": "lookup",
            "expected_latency_ms": 1,
            "custom_phrase": "text"
          },
          "result_persistence": "accumulate",
          "delivery": "interrupt",
          "failure_delivery": "interrupt",
          "failure_delivery_by_class": {
            "ANY_ADDITIONAL_PROPERTY": "interrupt"
          },
          "execution": "blocking",
          "lifecycle": "independent",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 1
        }
      ],
      "wait_for": "surface_submission",
      "guardrails": [
        {
          "name": "text",
          "description": "text",
          "enforcement": "hard"
        }
      ],
      "channel_overrides": {
        "ANY_ADDITIONAL_PROPERTY": {
          "objective": "text",
          "action_guidelines": [
            "text"
          ],
          "progress": {
            "deterministic": false,
            "phrases": [
              "text"
            ],
            "trigger_delay_ms": 1,
            "interval_ms": 1,
            "mode": "auto",
            "progress_class": "lookup",
            "expected_latency_ms": 1,
            "custom_phrase": "text"
          }
        }
      },
      "surface_spec_template": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "turn_policy": {
        "barge_in_enabled": true,
        "greeting_shield_s": 0,
        "safety_response": "stay_empathize",
        "context_strategy": "full",
        "degradation_threshold": -1,
        "block_forward_call": false,
        "block_forward_call_after_turns": -1,
        "stt_eot_threshold": 1,
        "stt_eager_eot_threshold": 1,
        "stt_eot_timeout_ms": 1
      },
      "preload": [
        {
          "tool_id": "text",
          "params": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ]
    }
  },
  "background_pending": false,
  "delivery": {
    "delivery_id": "123e4567-e89b-12d3-a456-426614174000",
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "receipt": "123e4567-e89b-12d3-a456-426614174000"
  },
  "delivery_protocol_version": 1
}

Acknowledge a rendered background turn delivery

post
Authorizations
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
delivery_idstring · uuidRequired
Body
request_idstring · uuidRequired
receiptstring · uuidRequired
Responses
204

Successful Response

No content

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

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "receipt": "123e4567-e89b-12d3-a456-426614174000"
}

No content

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
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
Header parameters
Idempotency-Keystring · uuid · nullableOptional

Stable UUID for replaying the same logical streamed user-input turn.

Body
messagestring · max: 10000OptionalDefault: ""
media_urlstring · max: 2048 · nullableOptional
media_typestring · max: 128 · nullableOptional
contextstring · max: 100000 · nullableOptional

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

viewport_widthinteger · min: 20 · max: 500 · nullableOptional
viewport_heightinteger · min: 5 · max: 500 · nullableOptional
wait_for_finalboolean · nullableOptional

Synchronous callers only: when a turn hands work to a background tool (background_pending), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with background_pending=false; on timeout it returns background_pending=true — resolve it later with poll=true. null (default) inherits the channel policy (web = do not wait). Ignored with poll=true (422).

suppress_fillerboolean · nullableOptional

Synchronous callers only: when a turn ends background_pending, omit the filler/acknowledgement text from output so a batch caller never mistakes the ack for the answer (output is empty; background_pending=true is the poll-later signal). null (default) inherits the channel policy. Ignored with poll=true (422).

Responses
200

SSE stream of TurnStreamEvent frames

anyOptional
post/v1/{workspace_id}/conversations/{conversation_id}/turns/stream
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: 300

{
  "message": "",
  "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,
  "wait_for_final": true,
  "suppress_filler": true
}

No content

Approve or reject a parked write in your own conversation (external-user self-approval)

post

Lets the external user who owns a conversation approve or reject a write that the agent paused for their confirmation. Only the conversation's own external user may call this; it requires the conversations:approve_own scope.

Authorizations
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
Body

An external user's decision on a parked, approval-gated write in their own conversation.

decisionstring · enumRequiredPossible values:
reasonstring · min: 1 · max: 512 · nullableOptional
Responses
204

Successful Response

No content

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

{
  "decision": "approve",
  "reason": "text"
}

No content

Last updated

Was this helpful?