Threads API

All REST endpoints require authentication via Auth0 JWT or API key.

GET /api/threads

List all threads for the authenticated user.

Response:

{
  "threads": [
    {
      "id": "thread_abc123",
      "name": "Fix login bug",
      "agentType": "claude-agent",
      "projectId": "proj_xyz",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T11:30:00Z",
      "archived": false,
      "tokenUsage": { "input": 12500, "output": 8900, "cost": "0.45" }
    }
  ]
}

POST /api/threads

Create a new thread.

{
  "agentType": "claude-agent",
  "name": "Fix login bug",
  "projectId": "proj_xyz",
  "metadata": {}
}

GET /api/threads/:id

Get thread details.

PATCH /api/threads/:id

Update thread metadata.

{
  "name": "Updated thread name",
  "settings": { "model": "claude-opus-4" },
  "projectId": "proj_new"
}

DELETE /api/threads/:id

Delete a thread and its session data.

GET /api/threads/:id/read

Read thread history — returns all turns, messages, and elements.

POST /api/threads/:id/messages

Send a message to the thread (equivalent to turn/start over WebSocket).

{
  "text": "Fix the failing test",
  "clientTurnId": "turn_local_1"
}

GET /api/threads/:id/events

SSE endpoint for thread events (alternative to WebSocket).

POST /api/threads/:id/stop

Stop the current turn (equivalent to turn/interrupt over WebSocket).

POST /api/threads/:id/steer

Send mid-turn guidance.

{
  "content": "Focus on error handling"
}

POST /api/threads/:id/approve

Respond to an approval request.

{
  "requestId": "req_123",
  "approved": true
}

POST /api/threads/:id/answer

Respond to a user input request.

{
  "requestId": "req_456",
  "answers": { "api_key": "sk-..." },
  "dismissed": false
}

POST /api/threads/:id/archive

Archive a thread.

POST /api/threads/:id/unarchive

Unarchive a thread.

GET /api/threads/:id/download

Download thread content as a file.

GET /api/threads/:id/session

Get active session info for a thread.