hub/docs/api.md

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