API Reference

Base URL#

All endpoints except auth and hook ingestion require authentication when a password is configured.

Session Endpoints#

| Method | Path | Description | |--------|------|-------------| | GET | /api/sessions | List all in-memory sessions | | PUT | /api/sessions/:id/title | Update session title | | PUT | /api/sessions/:id/label | Update session label | | PUT | /api/sessions/:id/accent-color | Update accent color | | POST | /api/sessions/:id/kill | Kill session (SIGTERM then SIGKILL) | | POST | /api/sessions/:id/resume | Resume ended SSH session | | POST | /api/sessions/:id/summarize | AI summarization | | DELETE | /api/sessions/:id | Delete session |

Kill Session#

curl -X POST http://localhost:3333/api/sessions/{id}/kill \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Sends SIGTERM, then SIGKILL after 3 seconds if the process hasn't exited.

Summarize Session#

curl -X POST http://localhost:3333/api/sessions/{id}/summarize \
  -H "Content-Type: application/json" \
  -d '{"context": "...", "promptTemplate": "..."}'

Uses Claude CLI (haiku model) to generate a summary. Maximum 2 concurrent requests.

Terminal Endpoints#

| Method | Path | Description | |--------|------|-------------| | POST | /api/terminals | Create PTY terminal (max 10) | | GET | /api/terminals | List active terminals | | DELETE | /api/terminals/:id | Close terminal |

Create Terminal#

curl -X POST http://localhost:3333/api/terminals \
  -H "Content-Type: application/json" \
  -d '{
    "host": "localhost",
    "username": "user",
    "workingDir": "~/projects/my-app",
    "command": "claude"
  }'

History & Analytics#

| Method | Path | Description | |--------|------|-------------| | GET | /api/db/sessions | Search sessions (paginated) | | GET | /api/db/sessions/:id | Full session detail | | GET | /api/db/search | Full-text search | | GET | /api/db/projects | Distinct projects | | GET | /api/db/analytics/summary | Summary stats | | GET | /api/db/analytics/tools | Tool breakdown | | GET | /api/db/analytics/projects | Active projects | | GET | /api/db/analytics/heatmap | Activity heatmap |

Search Sessions#

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | — | Text search in prompts | | project | string | — | Filter by project path | | status | string | — | Filter by status | | dateFrom | number | — | Start timestamp (ms) | | dateTo | number | — | End timestamp (ms) | | sortBy | string | started_at | Sort field | | sortDir | string | desc | asc or desc | | page | number | 1 | Page number | | pageSize | number | 50 | Results per page |

WebSocket Protocol#

Connect to ws://localhost:3333.

Server to Client#

| Type | Payload | When | |------|---------|------| | snapshot | {sessions, teams, seq} | On connection | | session_update | {session, team?} | State change | | session_removed | {sessionId} | Session deleted | | terminal_output | {terminalId, data} | PTY output (base64) | | terminal_ready | {terminalId} | PTY spawned | | terminal_closed | {terminalId, reason} | PTY exited | | hook_stats | {stats} | Performance data |

Client to Server#

| Type | Payload | Action | |------|---------|--------| | terminal_input | {terminalId, data} | Write to PTY stdin | | terminal_resize | {terminalId, cols, rows} | Resize PTY | | terminal_subscribe | {terminalId} | Subscribe to output | | replay | {sinceSeq} | Request missed events |

Reconnect#

On reconnect, send { type: "replay", sinceSeq: lastSeq } to receive missed events from the server's ring buffer (last 500 events).

Hook Ingestion#

POST /api/hooks
Content-Type: application/json

{"session_id": "...", "hook_event_name": "SessionStart", ...}

Rate limited to 100 requests/second per IP. This is the HTTP fallback — the primary transport is the file-based message queue.

Hook Management#

| Method | Path | Description | |--------|------|-------------| | GET | /api/hooks/status | Current density and installed events | | POST | /api/hooks/install | Install hooks at specified density | | POST | /api/hooks/uninstall | Remove all dashboard hooks |