Amigo conversations API
The conversations API from Amigo — 6 operation(s) for conversations.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account conversations API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: conversations
paths:
/v1/{workspace_id}/conversations:
post:
tags:
- conversations
summary: Create or start a conversation (web inbound, or outbound on a channel)
operationId: create_conversation_v1__workspace_id__conversations_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationRequest'
required: true
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
/v1/{workspace_id}/conversations/{conversation_id}/channel:
post:
tags:
- conversations
summary: Switch a conversation to another channel
description: 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.
operationId: switch_conversation_channel_v1__workspace_id__conversations__conversation_id__channel_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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SwitchChannelRequest'
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'
/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
- name: include_tool_calls
in: query
required: false
schema:
type: boolean
description: 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
title: Include Tool Calls
description: 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.
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:
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'
/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
- name: poll
in: query
required: false
schema:
type: boolean
description: Poll for background results without sending a user message. Drains any background tool calls that completed since the last turn and reports them; returns empty output when nothing is pending. Must NOT be combined with a request-body ``message`` (422) or SSE streaming (422). Poll no more than once every ~5s per conversation — each poll loads session state.
default: false
title: Poll
description: Poll for background results without sending a user message. Drains any background tool calls that completed since the last turn and reports them; returns empty output when nothing is pending. Must NOT be combined with a request-body ``message`` (422) or SSE streaming (422). Poll no more than once every ~5s per conversation — each poll loads session state.
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'
/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
/v1/{workspace_id}/conversations/{conversation_id}/approval:
post:
tags:
- conversations
summary: Approve or reject a parked write in your own conversation (external-user self-approval)
description: 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.
operationId: decide_conversation_approval_v1__workspace_id__conversations__conversation_id__approval_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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationApprovalRequest'
responses:
'204':
description: Successful Response
'403':
description: Not an external_user token, or missing conversations:approve_own scope
'404':
description: Conversation not found or not owned by the caller
'503':
description: Decision store temporarily unavailable — safe to retry
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
FailureClass:
type: string
enum:
- timeout
- input_rejected
- rounds_exhausted
- generic
title: FailureClass
description: 'Why a tool result is a failure — produced by the executor at RUN time.
Unlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime
classification the executor knows at the moment of failure. It flavors the
agent-facing failure wording and the world-event / status-tool observability,
and it is ALSO an optional routing key: a state x tool binding may set
``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class
(e.g. interrupt on timeout, queue on a generic error). With no per-class map
(the default), failed results route by the ``failure_delivery`` floor,
unchanged. Add a member only in the same change that wires a producer for it —
adding one also widens the per-class routing surface, so it must be a
deliberate, produced class.'
AnnotationState:
properties:
type:
type: string
const: annotation
title: Type
name:
type: string
title: Name
inner_thought:
type: string
title: Inner Thought
next_state:
type: string
title: Next State
type: object
required:
- type
- name
- inner_thought
- next_state
title: AnnotationState
description: Injects a hardcoded inner thought (no LLM call).
ChannelOverride:
properties:
objective:
anyOf:
- type: string
- type: 'null'
title: Objective
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
default: []
progress:
anyOf:
- $ref: '#/components/schemas/ProgressHint'
- type: 'null'
type: object
title: ChannelOverride
description: Per-channel behavior override for a state.
TurnErrorEvent:
description: 'Terminal error frame on the turn stream.
Carries a stable ``code`` so SDK consumers can branch deterministically
without parsing free-form ``message`` text. ``retryable`` tells the
consumer whether issuing the same turn again is likely to succeed.
``status_code`` is the upstream HTTP status when the error originated
from 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
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
background_pending:
default: false
description: True when the streamed response is only an acknowledgement and the final assistant answer must be collected with the durable background-delivery protocol.
title: Background Pending
type: boolean
delivery_protocol_version:
anyOf:
- const: 2
type: integer
- type: 'null'
default: null
description: Version of the durable background-delivery protocol supported by the serving agent. Clients may retry receipt-backed polls only after observing version 2.
title: Delivery Protocol Version
turn_id:
anyOf:
- format: uuid
type: string
- type: 'null'
default: null
description: Identifier of the user exchange this turn belongs to — identical to the ``turn_id`` on the non-streaming ``POST /turns`` response and on this conversation's history turns, so a streaming client can anchor durable per-turn artifacts (e.g. feedback) without a follow-up read. Stamped by platform-api at the proxy boundary (agent-engine frames do not carry it). Null when the conversation has no user exchange yet (a greeting kickoff stream on a fresh conversation).
title: Turn Id
turn_index:
anyOf:
- minimum: 0
type: integer
- type: 'null'
default: null
description: Zero-based ordinal of the user exchange (0 = first user turn). Derived server-side; null exactly when ``turn_id`` is null.
title: Turn Index
required:
- conversation_id
- status
- turn_count
title: TurnDoneEvent
type: object
TurnConversationSnapshot:
properties:
id:
type: string
format: uuid
title: Id
status:
type: string
enum:
- active
- closed
- completed
- in-progress
- failed
- paused
title: Status
turn_count:
type: integer
title: Turn Count
default: 0
updated_at:
type: string
title: Updated At
context_graph_state:
anyOf:
- $ref: '#/components/schemas/ContextGraphState-Output'
- type: 'null'
type: object
required:
- id
- status
- updated_at
title: TurnConversationSnapshot
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
ConversationApprovalRequest:
properties:
decision:
type: string
enum:
- approve
- reject
title: Decision
reason:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Reason
additionalProperties: false
type: object
required:
- decision
title: ConversationApprovalRequest
description: An external user's decision on a parked, approval-gated write in their own conversation.
TurnTokenEvent:
properties:
event:
const: token
default: token
title: Event
type: string
text:
title: Text
type: string
required:
- text
title: TurnTokenEvent
type: object
ProgressHint:
properties:
deterministic:
type: boolean
title: Deterministic
default: false
phrases:
anyOf:
- items:
type: string
type: array
maxItems: 10
minItems: 1
description: 'Filler phrases. deterministic=true: played verbatim in order. deterministic=false: used as hints for early attempts.'
- type: 'null'
title: Phrases
trigger_delay_ms:
anyOf:
- type: integer
maximum: 30000.0
minimum: 0.0
- type: 'null'
title: Trigger Delay Ms
interval_ms:
anyOf:
- type: integer
maximum: 30000.0
minimum: 100.0
- type: 'null'
title: Interval Ms
mode:
type: string
enum:
- auto
- silent
- backchannel
- verbal
title: Mode
default: auto
progress_class:
anyOf:
- type: string
enum:
- lookup
- write
- external_call
- compute
- multi_step
- type: 'null'
title: Progress Class
expected_latency_ms:
anyOf:
- type: integer
maximum: 60000.0
minimum: 0.0
- type: 'null'
title: Expected Latency Ms
custom_phrase:
anyOf:
- type: string
maxLength: 500
description: 'Legacy: use phrases instead.'
- type: 'null'
title: Custom Phrase
additionalProperties: false
type: object
title: ProgressHint
description: 'How the agent narrates waiting on a tool.
``deterministic=true``: scripted — ``phrases`` play verbatim in order.
``deterministic=false``: engine picks — ``phrases`` are hints.
``trigger_delay_ms``: milliseconds before first filler (0 = immediate).
``interval_ms``: milliseconds between subsequent fillers.'
ConversationDetail:
properties:
id:
type: string
format: uuid
title: Id
channel_kind:
$ref: '#/components/schemas/ChannelKind'
status:
type: string
enum:
- active
- closed
- completed
- in-progress
- failed
- paused
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
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.0
minimum: 0.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.
error_message:
anyOf:
- type: string
- type: 'null'
title: Error Message
description: Failure detail recorded for the tool call when ``succeeded`` is false. Null on successful calls or when no message was captured.
type: object
required:
- tool_name
- call_id
title: ConversationToolCallDetail
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.0
minimum: 20.0
- type: 'null'
title: Viewport Width
viewport_height:
anyOf:
- type: integer
maximum: 500.0
minimum: 5.0
- type: 'null'
title: Viewport Height
wait_for_final:
anyOf:
- type: boolean
- type: 'null'
title: Wait For Final
description: '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_filler:
anyOf:
- type: boolean
- type: 'null'
title: Suppress Filler
description: '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).'
type: object
title: TurnRequest
PhoneE164:
type: string
maxLength: 16
minLength: 2
ExitCondition:
properties:
description:
type: string
title: Description
next_state:
type: string
title: Next State
filler_hint:
anyOf:
- type: string
- type: 'null'
title: Filler Hint
type: object
required:
- description
- next_state
title: ExitCondition
DecisionState-Output:
properties:
type:
type: string
const: decision
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
exit_conditions:
items:
$ref: '#/components/schemas/ExitCondition'
type: array
title: Exit Conditions
decision_guidelines:
items:
type: string
type: array
title: Decision Guidelines
default: []
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
wait_for:
anyOf:
- type: string
enum:
- surface_submission
- human_approval
- type: 'null'
title: Wait For
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
type: object
required:
- type
- name
- objective
- exit_conditions
title: DecisionState
description: Passthrough routing state — Agent picks an exit condition, no user interaction.
ConversationTurnStateTransition:
properties:
from:
type: string
title: From
description: Source context-graph state before the turn's state transition.
to:
type: string
title: To
description: Destination context-graph state after the turn's state transition.
type: object
required:
- from
- to
title: ConversationTurnStateTransition
DataCollectionState-Output:
properties:
type:
type: string
const: data_collection
title: Type
name:
type: string
title: Name
objective:
type: string
title: Objective
fields:
items:
$ref: '#/components/schemas/CollectionField'
type: array
title: Fields
on_complete:
type: string
title: On Complete
action_guidelines:
items:
type: string
type: array
title: Action Guidelines
default: []
boundary_constraints:
items:
type: string
type: array
title: Boundary Constraints
default: []
surface_fallback:
type: boolean
title: Surface Fallback
default: false
surface_fallback_after_turns:
type: integer
title: Surface Fallback After Turns
default: 6
max_turns:
type: integer
title: Max Turns
default: 10
guardrails:
items:
$ref: '#/components/schemas/Guardrail'
type: array
title: Guardrails
default: []
channel_overrides:
additionalProperties:
$ref: '#/components/schemas/ChannelOverride'
type: object
title: Channel Overrides
turn_policy:
anyOf:
- $ref: '#/components/schemas/TurnPolicy'
- type: 'null'
tool_call_specs:
items:
$ref: '#/components/schemas/ToolCallSpec'
type: array
title: Tool Call Specs
default: []
type: object
required:
- type
- name
- objective
- fields
- on_complete
title: DataCollectionState
description: 'Structured voice/text data collection with field tracking.
The engine presents fields conversationally, tracks completion, and
optionally falls back to a Surface form after N turns. Each collected
field produces a world.event with confidence 0.5.'
PreloadSpec:
properties:
tool_id:
type: string
maxLength: 256
title: Too
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-conversations-api-openapi.yml