# API Documentation

This document documents all WebSocket actions and HTTP paths used by the WebSocket server.

## HTTP Paths

- `/` - Serves the frontend `index.html`
- `/user`, `/models`, `/remotes`, `/runs`, `/chat`, `/agent` - SPA routes
- `/chat/<path:subpath>`, `/agent/<path:subpath>` - SPA routes (subpaths handled by Vue router)
- `/<path:path>` - Static file routes
- `POST /user/login` - User login (supports token or username/password auth)
- `POST /user/signup` - User signup (creates default data after registration)
- `POST /api/openai/v1/chat/completions` - OpenAI-compatible chat completion endpoint
- `GET /api/openai/v1/models` - OpenAI-compatible models list endpoint

---

## WebSocket Actions (Client → Server)

### Authentication

- `ping` - Heartbeat; server responds with `"pong"`

### Agent Management

- `create-agent` - Creates a new agent
  - Payload: `name`, `agentname` (optional), `description` (optional), `picture` (optional), `kind`, `data` (optional), `temporary` (optional)
  - Response: `agentId`, `nonce`

- `update-agent` - Updates an existing agent
  - Payload: `agentId` or `agentname`, `name` (optional), `agentname` (optional), `description` (optional), `picture` (optional), `data` (optional)
  - Response: `agentId`, `nonce`

- `get-agent-config-fields` - Returns configuration schema fields for an agent
  - Payload: `agentId` or `agentname`
  - Response: `fields`, `nonce`

- `get-agent-kinds` - Returns all registered agent kinds
  - Response: `kinds`, `nonce`

- `get-agent-kind-info` - Returns details for a specific agent kind
  - Payload: `kind`
  - Response: `info`, `nonce`

- `get-agents` - Returns all agents for the authenticated user
  - Response: `agents`, `nonce`

- `get-agent-resources` - Returns agent resources
  - Payload: `agentId` or `agentname`, `kind` (optional), `key` (optional)
  - Response: `resources` list with `kind`, `key`, `value`

- `save-agent-resource` - Saves an agent resource
  - Payload: `agentId` or `agentname`, `kind`, `key`, `value`
  - Response: `nonce`

- `get-agent-runs` - Returns agent runs (optionally filtered by agent or user)
  - Payload: `agentId` or `agentname` (optional), `runId` (optional)
  - Response: `runs`, `nonce`

- `cancel-agent-run` - Cancels an agent run
  - Payload: `runId`

- `send-agent-prompt` - Sends a prompt to an agent
  - Payload: `agentId` or `agentname`, `instruction` or `input`, `options` (optional), `stream` (optional)
  - Response: `response` (stream ID if streaming, final content otherwise), `nonce`

### Model Management

- `get-models` - Returns all available models
  - Response: `models` list with `id`, `name`, `value`, `kind`, `nonce`

- `save-model` - Creates or deletes a model
  - Payload: `modelId` (optional), `name`, `kind`, `value`
  - Response: `message`, `modelId` or `message` with deletion, `nonce`

### Remote Management

- `remote-list` - Lists remotes for the authenticated user
  - Response: `remotes`, `nonce`

- `remote-connect` - Connects a new remote (served by this session)
  - Payload: `remotename`, `functions` array of `{name, description, parameters}`
  - Response: `remotename`, `nonce` (or error)

- `remote-disconnect` - Disconnects a remote
  - Payload: `remotename`
  - Response: `remotename`, `nonce` (or error if not found)

- `remote-call` - Invokes a function on a connected remote
  - Payload: `remotename`, `function`, `args`
  - Response: `result` or `error`, `nonce`

### Chat Management

- `create-chat` - Creates a new chat
  - Payload: `name`, `description` (optional), `picture` (optional), `members` (optional array of agent IDs), `temporary` (optional)
  - Response: `chatId`, `nonce`

- `get-chats` - Returns all chats for the authenticated user
  - Response: `chats`, `nonce`

- `delete-chat` - Deletes a chat
  - Payload: `chatId`
  - Response: `chatId`, `nonce`

- `get-chat-messages` - Returns messages for a chat (paginated)
  - Payload: `chatId`, `earliestIndex` (optional, defaults to 0)
  - Response: `messages`, `nonce`

- `send-chat-message` - Sends a chat message
  - Payload: `chatId`, `threadId` (optional), `content`, `kind` (optional), `subkind` (optional), `format` (optional)
  - Response: `messageId`, `nonce`

- `update-chat-message` - Updates a chat message
  - Payload: `messageId`, `content`, `kind` (optional), `subkind` (optional), `format` (optional)
  - Response: `messageId`, `nonce`

- `create-chat-thread` - Creates a new chat thread
  - Payload: `chatId`, `name` (optional)
  - Response: `threadId`, `nonce`

### Streaming

- `read-stream` - Reads the content of a stream incrementally
  - Payload: `streamId`
  - Response: `data` (chunks), `eof` (boolean), `fullData` (when eof is true), `nonce`

---

## WebSocket Actions (Server → Client)

### Agent Events

- `run-event` - Agent run event (used during chat messages and prompts)
  - Payload: event data, includes output, reasoning, tool calls, done state

### Remote Events

- `remote-call-result` - Result of a remote function call
  - Payload: `requestId`, `result`, `error`

### Authentication

- Server sends `"message": "authentication successful"` after successful authentication

### User Notifications

- `message` - Generic message type for various responses

---

## Common Response Fields

- `nonce` - Optional request identifier for matching responses
- `error` - Optional error message when an operation fails
- `message` - Confirmation message for successful operations