Conversations API

Conversations API

Overview

The Conversations API provides endpoints for viewing conversation history and replaying past interactions. This enables users to:

• Resume work from a previous conversation
• Review past decisions and agent interactions
• Create audit trails of agent activity

Endpoints

List User Conversations

Retrieve all conversation threads for a user across all workspaces.

Endpoint: GET /api/v1/conversations

Headers:

Query Parameters:

Response: WorkspaceThreadsListResponse

{
  "threads": [
    {
      "thread_id": "thread-abc123",
      "workspace_id": "ws-xyz789",
      "thread_index": 1,
      "current_status": "completed",
      "msg_type": "user",
      "first_query_content": "Create a hello world script",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

Example:

curl "http://localhost:8000/api/v1/conversations?limit=50" \
  -H "X-User-Id: user-123"

Get Thread Messages

Retrieve the complete message history for a specific conversation thread.

Endpoint: GET /api/v1/conversations/{thread_id}/messages

Path Parameters:

Query Parameters:

Response: WorkspaceMessagesResponse

{
  "workspace_id": "ws-xyz789",
  "user_id": "user-123",
  "name": "My Project",
  "messages": [
    {
      "pair_index": 0,
      "thread_id": "thread-abc123",
      "thread_index": 1,
      "query": {
        "query_id": "q-001",
        "content": "Create a hello world script",
        "type": "user",
        "timestamp": "2025-01-15T10:30:00Z"
      },
      "response": {
        "response_id": "r-001",
        "status": "completed",
        "agent_messages": [...],
        "execution_time": 12.5,
        "timestamp": "2025-01-15T10:30:12Z"
      }
    }
  ],
  "total_messages": 5,
  "has_more": false,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}

Example:

curl "http://localhost:8000/api/v1/conversations/thread-abc123/messages?limit=100"

Replay Thread (SSE) -- Prefer this over the messages endpoint!

Stream the complete history of a thread as Server-Sent Events. This endpoint replays persisted streaming chunks, allowing clients to reconstruct the conversation display exactly as it occurred.

Endpoint: GET /api/v1/threads/{thread_id}/replay

Path Parameters:

Response: text/event-stream

The endpoint streams events that replay the original conversation:

SSE Event Types

Event Format:

id: 1
event: user_message
data: {"thread_id": "thread-abc123", "pair_index": 0, "content": "Create a hello world script", "timestamp": "2025-01-15T10:30:00Z"}

id: 2
event: message_chunk
data: {"content": "I'll create a simple Python script for you.", "agent": "assistant", "thread_id": "thread-abc123", "pair_index": 0, "response_id": "r-001"}

id: 3
event: tool_calls
data: {"tool_name": "write_file", "arguments": {"path": "/workspace/hello.py", "content": "print('Hello World')"}, "tool_call_id": "call_001", "thread_id": "thread-abc123", "pair_index": 0, "response_id": "r-001"}

id: 4
event: tool_call_result
data: {"tool_name": "write_file", "result": "File created successfully", "tool_call_id": "call_001", "thread_id": "thread-abc123", "pair_index": 0, "response_id": "r-001"}

id: 5
event: replay_done
data: {"thread_id": "thread-abc123"}

Example with curl:

curl -N "http://localhost:8000/api/v1/threads/thread-abc123/replay"

Continuing a Conversation

After replaying a conversation, users can continue from where it left off:

1. Replay completes - History is displayed to the user
2. User sends new message - CLI submits to /api/v1/chat/stream with:
   • Same workspace_id from the conversation
   • Same thread_id to continue the thread
3. Agent resumes - Agent has full context from previous interactions

Example flow:

# 1. User selects conversation from /conversation menu
# 2. CLI replays history via GET /api/v1/threads/{thread_id}/replay
# 3. User types a new message
# 4. CLI sends to POST /api/v1/chat/stream:

curl -N -X POST "http://localhost:8000/api/v1/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "workspace_id": "ws-xyz789",
    "thread_id": "thread-abc123",
    "messages": [
      {
        "role": "user",
        "content": "Now add error handling to that script"
      }
    ]
  }'

The agent will have full context from the replayed conversation and can continue the work.

Error Responses

Error Response Format:

{
  "detail": "Thread not found: thread-abc123"
}