Conversations API
Manage multi-turn conversations between users and agents. Conversations persist across sessions and maintain full message history.
Base path: /api/v1/conversations
Endpoints
List Conversations
GET /api/v1/conversations
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
limit | integer | Results per page (default: 20, max: 100) |
agentId | string | Filter by agent |
status | string | active, completed, archived |
Response:
{
"conversations": [
{
"id": "conv_abc123",
"name": "Lead qualification - Acme Corp",
"agentId": "agent_456",
"status": "active",
"messageCount": 8,
"lastMessageAt": "2026-04-12T14:30:00Z",
"createdAt": "2026-04-12T14:00:00Z"
}
],
"total": 34
}
Create Conversation
POST /api/v1/conversations
| Field | Type | Required | Description |
|---|---|---|---|
agentId | string | Yes | Agent to converse with |
name | string | No | Conversation title |
appId | string | No | Workspace scope |
metadata | object | No | Custom tags (ticket ID, priority, etc.) |
Response (201):
{
"id": "conv_new789",
"agentId": "agent_456",
"status": "active",
"createdAt": "2026-04-12T15:00:00Z"
}
Get Conversation
GET /api/v1/conversations/:id
Returns conversation details including participant info and metadata.
Get Messages
GET /api/v1/conversations/:id/messages
Returns the full message history for a conversation.
| Parameter | Type | Description |
|---|---|---|
limit | integer | Max messages (default: 50) |
before | string | Cursor for pagination (message ID) |
Response:
{
"messages": [
{
"id": "msg_001",
"role": "user",
"content": "Research the lead from Acme Corp",
"createdAt": "2026-04-12T14:00:00Z"
},
{
"id": "msg_002",
"role": "assistant",
"content": "I found 3 contacts at Acme Corp in HubSpot...",
"toolCalls": [
{
"name": "hubspot_search",
"input": { "query": "company:Acme" }
}
],
"tokenUsage": { "inputTokens": 850, "outputTokens": 220 },
"createdAt": "2026-04-12T14:00:03Z"
}
],
"hasMore": false
}
Send Message
POST /api/v1/conversations/:id/messages
Send a message to an active conversation. The agent responds using its full context (system prompt, memory, tools, conversation history).
| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Message text |
attachments | array | No | File attachment IDs |
Response:
{
"message": {
"id": "msg_003",
"role": "assistant",
"content": "Based on my research, here's the qualification summary...",
"toolCalls": [],
"tokenUsage": { "inputTokens": 1100, "outputTokens": 450 }
},
"cost": 0.0045
}
Delete Conversation
DELETE /api/v1/conversations/:id
Soft-deletes the conversation. Audit trail is preserved.
Conversation Stats
GET /api/v1/conversations/stats
Returns aggregate statistics: total conversations, active count, average duration, message counts.
Streaming
For real-time responses, use the agent's streaming endpoint instead of the conversation message endpoint:
POST /api/v1/agents/:agentId/stream
This returns Server-Sent Events (SSE) with token-by-token output:
event: token
data: {"text": "Based"}
event: token
data: {"text": " on"}
event: tool_call_start
data: {"id": "tc_1", "name": "hubspot_search"}
event: tool_call_end
data: {"id": "tc_1", "result": {"contacts": 3}}
event: done
data: {"conversationId": "conv_789", "cost": 0.0034}
Live Message Injection
You can send messages while an agent is still responding:
POST /api/v1/conversations/:id/inject
The agent picks up injected messages at its next processing boundary. This is useful for corrections, additional context, or changing direction mid-task.