API Reference
Conversation API
Start chat memory, continue chats, fetch messages, and list conversations.
What this API is for
Use this when chat should remember earlier messages.
You do not need to build your own conversation storage.
POST /v1/runner/{deployment_id}/conversation
Creates a new conversation.
Request body
| Field | Type | Required | Meaning |
|---|---|---|---|
content | array | Yes | First user message |
meta | object | No | Your custom labels |
variables | object | No | Prompt variable values |
Example request
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": "Hi, I need help with billing." }
]
}'Example response
{
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Billing support",
"content": "Sure. I can help with billing.",
"input_tokens": 14,
"output_tokens": 20
}POST /v1/runner/{deployment_id}/conversation/stream
Continues an existing conversation in streaming mode.
Request body
| Field | Type | Required | Meaning |
|---|---|---|---|
conversation_id | string | Yes | Existing conversation ID |
content | array | Yes | New user message |
history_limit | number | No | Number of previous turns to include |
Example request
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": "550e8400-e29b-41d4-a716-446655440000",
"content": [
{ "type": "text", "text": "Please summarize in 2 bullets." }
],
"history_limit": 5
}'GET /v1/runner/conversation/{conversation_id}/messages
Gets paginated messages for one conversation.
Query params
| Param | Type | Required | Meaning |
|---|---|---|---|
page | number | No | Page number (default 1) |
page_size | number | No | Items per page (default 20) |
Example response
{
"items": [
{
"id": "msg_1",
"role": "user",
"content": "Hi",
"created_at": "2026-03-24T09:00:00Z"
},
{
"id": "msg_2",
"role": "assistant",
"content": "Hello! How can I help?",
"created_at": "2026-03-24T09:00:02Z"
}
],
"total": 2,
"page": 1,
"page_size": 20,
"has_more": false
}GET /v1/runner/conversations
Lists conversations (paginated).
Query params
| Param | Type | Required | Meaning |
|---|---|---|---|
page | number | No | Page number |
page_size | number | No | Items per page |
any meta key | string | No | Filter conversations by metadata |
Example response
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Billing support",
"meta": {
"userId": "user_123",
"projectId": "project_456"
},
"created_at": "2026-03-24T09:00:00Z",
"updated_at": "2026-03-24T09:01:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20,
"has_more": false
}What is meta?
meta is optional key-value data you attach to conversations.
Example:
{
"meta": {
"userId": "user_123",
"projectId": "project_456",
"source": "web-chat"
}
}Use meta for filtering, analytics, and routing.