Conversation API

Reference the unchanged v1 endpoints and SDK methods for ordinary stateful and streaming conversations.

Overview

The v1 conversation API provides ordinary multi-turn chat and streaming. It is unchanged: existing clients can continue using it and ignore the additive lifecycle fields now returned by message and list reads.

Use the agent conversation API for durable client actions, reconnect, progress, and permanent completion.

POST `/v1/runner/{deployment_id}/conversation`

Start a conversation by omitting conversation_id, or continue by including it.

curl https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID/conversation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "content": [{ "type": "text", "text": "Help me with my order." }],
    "variables": { "CUSTOMER_TIER": "pro" },
    "meta": { "userId": "user_123" }
  }'

Field	Type	Required	Notes
`content`	`MessageContent[]`	Yes	Text or supported multimodal parts
`conversation_id`	UUID	No	Include to continue
`variables`	object of strings	No	Initial message only
`meta`	object	No	Initial message only
`history_limit`	integer	No	Prior message pairs; default `5`
`trigger_id`	string	No	Initial message only

{
  "conversation_id": "8bd6d8ca-fc71-4d46-858b-e50b4a9bf83b",
  "status": "active",
  "completed_at": null,
  "name": "Order help",
  "content": "What is your order number?",
  "input_tokens": 30,
  "output_tokens": 8,
  "response_time": 0.82
}

POST `/v1/runner/{deployment_id}/conversation/stream`

Streams the assistant response for an ordinary conversation.

curl -N https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID/conversation/stream \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "conversation_id": "8bd6d8ca-fc71-4d46-858b-e50b4a9bf83b",
    "content": [{ "type": "text", "text": "Summarize the options." }],
    "history_limit": 10
  }'

Use -N to avoid curl buffering. Durable agent v2 execution does not stream.

GET `/v1/runner/conversation/{conversation_id}/messages`

Returns paginated actual messages. Tool calls and results are not inserted into items.

curl "https://api.amarsia.com/v1/runner/conversation/8bd6d8ca-fc71-4d46-858b-e50b4a9bf83b/messages?page=1&page_size=20" \
  -H "x-api-key: YOUR_API_KEY"

{
  "items": [{
    "id": 301,
    "role": "user",
    "content": [{ "type": "text", "text": "Help me with my order." }],
    "created_at": "2026-07-11T15:10:00Z"
  }],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "conversation_status": "active",
  "completed_at": null,
  "run_id": null,
  "run_status": null,
  "pending_client_actions": [],
  "tool_summary": [],
  "progress": []
}

The final seven fields are additive reconnect state. Existing v1 clients can ignore them.

GET `/v1/runner/{deployment_id}/conversations`

Lists conversations with pagination and metadata filters:

curl "https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID/conversations?page=1&page_size=20&userId=user_123" \
  -H "x-api-key: YOUR_API_KEY"

List items also include optional status, completed_at, run_id, run_status, pending_client_actions, tool_summary, and progress.

SDK

client.conversation.start()
const created = await client.conversation.run({
  content: [{ type: "text", text: "Help me with my order." }],
  meta: { userId: "user_123" },
})

client.conversation.start(created.conversation_id)
await client.conversation.stream({
  content: [{ type: "text", text: "Summarize the options." }],
  historyLimit: 10,
})

await client.conversation.loadMessages({ page: 1, pageSize: 20 })
await client.conversation.list({ meta: { userId: "user_123" } })

loadMessages() returns only message items and pagination state through client.conversation. Use client.agent.open() when your application needs the additive durable lifecycle state.

React

const {
  conversation,
  id,
  status,
  live,
  data,
  messages,
  conversations,
} = useConversation(client)

useConversation is a thin reactive wrapper over the same v1 SDK controller.

Conversation API

On this page