Conversations
Conversations are chat sessions between you and the Claude agent. They are created automatically when you send a message through the chat WebSocket. The API provides read-only access to conversation history -- new conversations are initiated through the WebSocket protocol, not the REST API.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/conversations | List recent conversations |
| GET | /api/conversations/:id | Get a conversation with messages |
| DELETE | /api/conversations/:id | Delete a conversation |
All endpoints require authentication.
List Conversations
GET /api/conversations
Return the 50 most recent conversations, ordered by start time (newest first). Does not include message content.
Response: 200 OK
{
"data": [
{
"id": "conv-123",
"sessionId": "sess-abc",
"title": "Database migration help",
"summary": "Helped with Drizzle ORM migration setup",
"status": "idle",
"totalCostUsd": 0.042,
"messageCount": 8,
"startedAt": "2025-01-07T10:00:00.000Z",
"endedAt": "2025-01-07T10:15:00.000Z"
}
]
}
Get Conversation
GET /api/conversations/:id
Return a single conversation with all of its messages. Message content is parsed from stored JSON into structured content blocks.
Response: 200 OK
{
"data": {
"id": "conv-123",
"sessionId": "sess-abc",
"title": "Database migration help",
"status": "idle",
"totalCostUsd": 0.042,
"messageCount": 8,
"startedAt": "2025-01-07T10:00:00.000Z",
"messages": [
{
"id": "msg-1",
"conversationId": "conv-123",
"role": "user",
"content": [{ "type": "text", "text": "How do I add a column?" }],
"createdAt": "2025-01-07T10:00:00.000Z"
},
{
"id": "msg-2",
"conversationId": "conv-123",
"role": "assistant",
"content": [{ "type": "text", "text": "You can add a column with..." }],
"costUsd": 0.005,
"durationMs": 2300,
"createdAt": "2025-01-07T10:00:05.000Z"
}
]
}
}
Returns 404 if the conversation does not exist.
Message Content Blocks
Each message's content field is an array of typed blocks:
| Type | Fields | Description |
|---|---|---|
text | text | Plain text or markdown |
tool_use | id, name, input | Tool invocation by the assistant |
tool_result | tool_use_id, content, is_error | Result returned to the assistant |
Delete Conversation
DELETE /api/conversations/:id
Permanently delete a conversation and all of its messages. This is a hard delete -- there is no restore.
Conversation deletion is permanent. Messages cannot be recovered after deletion.
Response: 200 OK
{
"data": {
"success": true
}
}