API Reference

Base URL: http://localhost:3030

REST API

Health Check

GET /health

{ "status": "healthy", "version": "0.1.0" }

List Sessions

GET /api/sessions?include_archived=false

{
  "sessions": [
    {
      "id": "uuid",
      "name": "session-name",
      "backend": "docker",
      "agent": "claude",
      "status": "running",
      "repo_path": "/home/user/project",
      "created_at": "2024-01-15T10:30:00Z",
      "archived": false
    }
  ]
}

Get Session

GET /api/sessions/:id

Returns full session including chat_history, prompt, worktree_path.

Create Session

POST /api/sessions

Single repo:

{
  "repo_path": "/home/user/project",
  "prompt": "Fix the login bug",
  "backend": "docker",
  "agent": "claude",
  "model": "claude-sonnet-4-5"
}

Multi-repo:

{
  "name": "multi-repo-session",
  "repositories": [
    { "path": "/home/user/project1", "mount_name": "main" },
    { "path": "/home/user/project2", "mount_name": "lib" }
  ],
  "prompt": "Refactor shared code",
  "backend": "docker",
  "agent": "claude"
}

Field	Type	Required	Description
repo_path	string	Yes*	Single repository path
repositories	array	Yes*	Multi-repo array (max 5)
prompt	string	Yes	Initial prompt
backend	string	No	Backend type
agent	string	No	Agent type (default: “claude”)
no_plan_mode	boolean	No	Disable plan mode
model	string	No	Model override
name	string	No	Custom session name
base_branch	string	No	Git base branch
image_paths	array	No	Image attachments

* Either repo_path or repositories required

Delete Session

DELETE /api/sessions/:id?force=false

Archive / Unarchive

POST /api/sessions/:id/archive
POST /api/sessions/:id/unarchive

Refresh Session

POST /api/sessions/:id/refresh

Pulls latest image and recreates container (Docker only).

Start / Recreate / Cleanup

POST /api/sessions/:id/start
POST /api/sessions/:id/recreate          # body: { "fresh": false }
POST /api/sessions/:id/recreate-fresh
POST /api/sessions/:id/cleanup

Get Session Health

GET /api/sessions/:id/health

{
  "session_id": "uuid",
  "health": "Error",
  "details": {
    "container_status": "exited",
    "exit_code": 1,
    "error_message": "OCI runtime error"
  },
  "available_actions": ["recreate", "recreate_fresh", "cleanup"],
  "data_preservation": {
    "recreate": true,
    "recreate_fresh": false,
    "cleanup": false
  },
  "reconciliation": { "attempts": 2, "last_attempt": "2025-01-28T12:30:00Z" }
}

Update / Regenerate Metadata

POST /api/sessions/:id/metadata

{ "name": "new-name", "description": "...", "tags": ["feature-x"] }

POST /api/sessions/:id/regenerate-metadata

AI-generated metadata from chat history. Requires ai_metadata = true.

Upload Files

POST /api/sessions/:id/upload

Multipart form data. Files uploaded to session working directory.

Browse Directory

POST /api/browse-directory

{ "path": "/home/user/projects", "show_hidden": false }

Get Config

GET /api/config

WebSocket API

Event Stream

ws://localhost:3030/ws/events

Subscribe/Unsubscribe:

{ "type": "subscribe", "session_id": "uuid" }
{ "type": "unsubscribe", "session_id": "uuid" }

Events received: session_status, chat_message, tool_call, tool_result

Send message:

{ "type": "send_message", "session_id": "uuid", "content": "..." }

Keep-alive: { "type": "ping" } / { "type": "pong" }

Terminal Console

ws://localhost:3030/ws/console/{sessionId}?cols=120&rows=40

Binary protocol for terminal I/O. JSON for resize/error messages:

{ "type": "resize", "cols": 120, "rows": 40 }
{ "type": "error", "message": "Session not found" }

xterm.js example:

import { Terminal } from "xterm";
import { FitAddon } from "xterm-addon-fit";

const term = new Terminal();
const fitAddon = new FitAddon();
term.loadAddon(fitAddon);
term.open(document.getElementById("terminal"));
fitAddon.fit();

const ws = new WebSocket(`ws://localhost:3030/ws/console/${sessionId}`);
ws.onopen = () =>
  ws.send(JSON.stringify({ type: "resize", cols: term.cols, rows: term.rows }));
term.onData((data) => ws.send(data));
ws.onmessage = (event) => {
  if (event.data instanceof Blob)
    event.data.text().then((text) => term.write(text));
  else term.write(event.data);
};

PTY remains attached on disconnect (session continues running).

Error Responses

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session with ID 'xyz' not found"
  }
}

Code	HTTP	Description
SESSION_NOT_FOUND	404	Session doesn’t exist
BACKEND_ERROR	500	Backend operation failed
INVALID_REQUEST	400	Invalid request body
UNAUTHORIZED	401	Authentication required
FORBIDDEN	403	Operation not allowed
CONFLICT	409	Resource already exists

Authentication

Default: none (localhost only). With WebAuthn:

Authorization: Bearer <token>
Cookie: clauderon_session=<token>

CORS allows same origin and localhost:* / 127.0.0.1:*.