# Chat & Conversations
Send messages to ARES agents and manage multi-turn conversations.
---
## Send a message
```
POST /api/chat
```
Send a message to an agent and receive a response. ARES routes the message to the appropriate agent based on the `agent_type` parameter, or uses the default router agent if none is specified.
### Authentication
Requires a JWT access token: `Authorization: Bearer <jwt_access_token>`
### Request body
| `message` | string | Yes | The user's message or prompt. |
| `agent_type` | string | No | Which agent handles the request (e.g., `"product"`, `"research"`, `"router"`). Defaults to the router agent. |
| `context_id` | string | No | Conversation context ID. Pass this value back on subsequent requests to continue a multi-turn conversation. |
### Response
```json
{
"response": "Here's what I found about your question...",
"agent": "product",
"context_id": "ctx_a1b2c3d4",
"sources": null
}
```
| `response` | string | The agent's response text. |
| `agent` | string | The agent that handled the request. |
| `context_id` | string | Context identifier. Pass this back to continue the conversation. |
| `sources` | array\|null | Source references, if the agent performed retrieval. Otherwise `null`. |
### Examples
#### curl
```bash
curl -X POST http://localhost:3000/api/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOi..." \
-d '{
"message": "What pricing plans do you offer?",
"agent_type": "product"
}'
```
#### Python
```python
import requests
response = requests.post(
"http://localhost:3000/api/chat",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi..."
},
json={
"message": "What pricing plans do you offer?",
"agent_type": "product"
}
)
data = response.json()
print(data["response"])
# Continue the conversation using the returned context_id
follow_up = requests.post(
"http://localhost:3000/api/chat",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi..."
},
json={
"message": "How does the Pro plan compare to Enterprise?",
"context_id": data["context_id"]
}
)
```
#### JavaScript
```javascript
const response = await fetch("http://localhost:3000/api/chat", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi..."
},
body: JSON.stringify({
message: "What pricing plans do you offer?",
agent_type: "product"
})
});
const data = await response.json();
console.log(data.response);
// Continue the conversation
const followUp = await fetch("http://localhost:3000/api/chat", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi..."
},
body: JSON.stringify({
message: "How does the Pro plan compare to Enterprise?",
context_id: data.context_id
})
});
```
---
## Stream a response
```
POST /api/chat/stream
```
Send a message and receive the response as a stream of Server-Sent Events (SSE). Each event contains a text chunk. This is the recommended approach for user-facing applications where you want to display the response as it is generated.
The request body is identical to `POST /api/chat`.
### Authentication
Requires a JWT access token: `Authorization: Bearer <jwt_access_token>`
### Response format
The response uses the `text/event-stream` content type. Each SSE event contains a chunk of the agent's response:
```
data: Here's
data: what I
data: found about
data: your question...
```
Collect all chunks to form the complete response. The connection closes automatically when the response is complete.
### Examples
#### curl
```bash
curl -N -X POST http://localhost:3000/api/chat/stream \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOi..." \
-H "Accept: text/event-stream" \
-d '{
"message": "Explain quantum computing",
"agent_type": "research"
}'
```
#### Python
```python
import requests
response = requests.post(
"http://localhost:3000/api/chat/stream",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi...",
"Accept": "text/event-stream"
},
json={
"message": "Explain quantum computing",
"agent_type": "research"
},
stream=True
)
for line in response.iter_lines():
if line:
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
chunk = decoded[6:] # Strip "data: " prefix
print(chunk, end="", flush=True)
```
#### JavaScript
```javascript
const response = await fetch("http://localhost:3000/api/chat/stream", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOi...",
"Accept": "text/event-stream"
},
body: JSON.stringify({
message: "Explain quantum computing",
agent_type: "research"
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value, { stream: true });
for (const line of text.split("\n")) {
if (line.startsWith("data: ")) {
const chunk = line.slice(6);
process.stdout.write(chunk); // Node.js
// Or append to DOM in browsers
}
}
}
```
---
## Conversations
Manage stored conversations and their message history.
### List conversations
```
GET /api/conversations
```
Returns all conversations for the authenticated user.
**Authentication:** JWT required.
```bash
curl http://localhost:3000/api/conversations \
-H "Authorization: Bearer eyJhbGciOi..."
```
### Get a conversation
```
GET /api/conversations/{id}
```
Returns a single conversation along with its full message history.
**Authentication:** JWT required.
| `id` | string | path | The conversation ID |
```bash
curl http://localhost:3000/api/conversations/conv_abc123 \
-H "Authorization: Bearer eyJhbGciOi..."
```
### Update a conversation
```
PUT /api/conversations/{id}
```
Update the title of a conversation.
**Authentication:** JWT required.
**Request body:**
```json
{
"title": "Pricing discussion"
}
```
```bash
curl -X PUT http://localhost:3000/api/conversations/conv_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOi..." \
-d '{"title": "Pricing discussion"}'
```
### Delete a conversation
```
DELETE /api/conversations/{id}
```
Permanently delete a conversation and all its messages.
**Authentication:** JWT required.
```bash
curl -X DELETE http://localhost:3000/api/conversations/conv_abc123 \
-H "Authorization: Bearer eyJhbGciOi..."
```
---
## User memory
```
GET /api/memory
```
Retrieve memory and preferences that ARES has learned from your conversations. This includes user preferences, context, and behavioral patterns the system has observed.
**Authentication:** JWT required.
```bash
curl http://localhost:3000/api/memory \
-H "Authorization: Bearer eyJhbGciOi..."
```