webtop-manage
webtop-manage v1.0.0
/docs/api/reference
Developer ReferenceAPI webtop-manage v1.0.0

REST, SSE & WS API Reference

Complete specification of all REST endpoints, Server-Sent Events, and WebSocket terminal protocols.

REST, SSE & WS API Reference

Base URL: http://127.0.0.1:8080/api

📋 Endpoints Overview

MethodEndpointDescriptionResponse / Protocol
GET/api/healthService health status and Clean Architecture metadata.200 OK (JSON)
GET/api/configActive runtime system configuration.200 OK (JSON)
GET/api/themesAvailable UI themes (themes.json).200 OK (JSON)
GET/api/system/fs?path=...Host filesystem directory browser with quick roots.200 OK (JSON)
GET/api/catalog/presetsCurated workstation presets with host image cache status.200 OK (JSON)
GET/api/catalog/matrixValidated Distro and Desktop Environment combinations.200 OK (JSON)
GET/api/catalog/ports/next?base_port=3000Scans host TCP ports and returns the next free port.200 OK (JSON)
GET/api/catalog/image-status?image=...Checks whether an image tag is cached locally.200 OK (JSON)
GET/api/instancesList all discovered and managed Webtop instances.200 OK (JSON)
POST/api/instancesProvisions a new workstation (Supports SSE streaming).201 Created or text/event-stream
GET/api/instances/{id}Retrieve details for a specific workstation.200 OK (JSON)
DELETE/api/instances/{id}?delete_volume=...Removes container, network, and optionally persistent volumes.200 OK (JSON)
POST/api/instances/{id}/(start|stop|restart|pause|unpause)Lifecycle state action execution.200 OK (JSON)
POST/api/instances/{id}/resourcesLive-updates CPU cores and Memory limits without rebooting.200 OK (JSON)
POST/api/instances/{id}/volumesDynamically attaches a volume or host path mount.200 OK (JSON)
GET/api/volumesLists all Docker volumes on the host.200 OK (JSON)
GET/api/instances/{id}/statsReal-time CPU %, RAM MB / %, and Network metrics.text/event-stream (SSE)
GET/api/instances/{id}/logs?tail=150Live streaming stdout/stderr container logs.text/event-stream (SSE)
GET/api/instances/{id}/terminalInteractive root PTY shell session (/bin/bash).101 Switching Protocols (WS)
GET/api/networksList Docker bridge networks.200 OK (JSON)
POST/api/instances/{id}/networks/connectAttach an instance to a Docker network.200 OK (JSON)
POST/api/instances/{id}/networks/disconnectDetach an instance from a Docker network.200 OK (JSON)

🛠️ Key Endpoint Specifications

POST /api/instances (Provisioning Stream)

Request Payload

json
{
  "name": "sonic-ubuntu-850",
  "preset": "ubuntu-xfce",
  "image": "lscr.io/linuxserver/webtop:ubuntu-xfce",
  "host_ip": "127.0.0.1",
  "host_port": 3000,
  "internal_port": 3000,
  "custom_user": "abc",
  "password": "secretpassword",
  "shm_size_mb": 1024,
  "cpu_limit": 2.0,
  "memory_limit_mb": 4096,
  "gpu_acceleration": false,
  "config_volume": "",
  "workspace_volume": "",
  "custom_host_bind": "",
  "networks": [],
  "egress_policy": "full",
  "auto_start": true
}

SSE Stream Events (Accept: text/event-stream)

  • Progress: event: progress\ndata: {"status": "Pulling layers..."}\n\n
  • Done: event: done\ndata: {"id": "c1f98a2e7d80", "name": "sonic-ubuntu-850", "host_port": 3000}\n\n
  • Error: event: error\ndata: {"error": "Port conflict on 3000"}\n\n

POST /api/instances/{id}/resources (Live Zero-Downtime Update)

json
{
  "cpu_limit": 2.5,
  "memory_limit_mb": 8192
}

GET /api/instances/{id}/terminal (WebSocket PTY)

  • Raw Frames: Bidirectional stdin / stdout.
  • Control Resize Frame (Client $\rightarrow$ Server):
    json
    {
  "type": "resize",
  "cols": 120,
  "rows": 40
}