156 lines
5.3 KiB
Markdown
156 lines
5.3 KiB
Markdown
# 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 |