π MOS API Reference
This is the complete, interactive reference for the MOS REST API. It mirrors the
built-in Swagger UI at http://<MOS-IP>/api-docs/ and covers every endpoint, parameter,
request/response schema and example request.
Most endpoints require a Bearer token. Create one in the WebUI under
User Settings β Admin API Tokens, then send it in the Authorization header:
Authorization: Bearer <TOKEN>
This reference is regenerated automatically from the mos-nas/mos-api repository every Sunday around 23:00 (Austrian time, CET/CEST). A manual update can be triggered any time via the Sync OpenAPI Reference workflow on the Actions tab of the mos-docs repository.
Last sync: 04.11.2026, 14:22 GMT+1 | mode: manual | source: mos-api@8051d78cb9
Endpointsβ
Interactive reference for the MOS API (v0.1.0). Base path: /api/v1. Configure your server and token below to make every example copy-ready, or leave the defaults to use <MOS-IP> / <TOKEN> placeholders.
Filter to find endpoints fast, click a category to expand it, then open an endpoint for parameters, schemas and example requests. Use the # on any endpoint or category to copy a direct, shareable link.
Authentication. User authentication and management
GET /auth/firstsetup. Get first setup token. Returns the boot token if it exists in the token file, otherwise returns null. Used for initial system setup. This endpoint requires no authentication. Responses: 200, 500.
POST /auth/login. User login. Body: username, password. Responses: 200, 400, 401, 429.
POST /auth/mfa. Verify MFA code during login. Verify TOTP code or recovery code to complete MFA login. Accepts the temporary mfa token from login response. If recovery code is used, MFA is automatically disabled. Body: mfa_token, code. Responses: 200, 401.
DELETE /auth/mfa. Disable MFA. Disable MFA for the authenticated user. Requires password confirmation. Removes all MFA data. Body: password. Responses: 200, 400, 401.
POST /auth/mfa/setup. Setup or confirm MFA. Two-step MFA setup: - Without code: Generates TOTP secret, returns QR code and secret for manual entry - With code: Verifies TOTP code and activates MFA, returns recovery code Password is always required for security. Body: password, code. Responses: 200, 400, 401.
GET /auth/users. Get users (admin sees all, user sees only themselves). Retrieve users - admins can see all users with optional filtering, normal users only see their own profile (both return arrays) Parameters: samba_user. Responses: 200, 401, 500.
POST /auth/users. Create new user (admin only). Body: username, password, role, samba_user. Responses: 201, 400, 401, 403.
PUT /auth/users/{id}. Update user (admin can update any user, users can update themselves). Update user information - admins can update any user, normal users can only update their own profile with limited fields Parameters: id. Body: username, password, role, samba_user. Responses: 200, 400, 401, 403.
DELETE /auth/users/{id}. Delete user (admin only). Parameters: id. Responses: 204, 400, 401, 403.
GET /auth/profile. Get own user profile. Responses: 200, 401, 404, 500.
POST /auth/logout. User logout. Invalidate the current session. Note that JWT tokens cannot be truly invalidated server-side, but this endpoint provides a consistent logout mechanism. Responses: 200, 401.
GET /auth/jwt-settings. Get JWT settings. Retrieve current JWT token expiry settings (admin only) Responses: 200, 401, 403, 500.
PUT /auth/jwt-settings. Update JWT expiry time. Update JWT token expiry time in days (admin only) Body: expiryDays. Responses: 200, 400, 401, 403, 500.
GET /auth/admin-tokens. Get all admin tokens. Retrieve list of all admin API tokens (admin only) Responses: 200, 401, 403, 500.
POST /auth/admin-tokens. Create admin token. Create a new permanent admin API token (admin only) Body: name, description, permissions. Responses: 201, 400, 401, 403, 500.
GET /auth/admin-tokens/me. Get current token permissions. Introspect the permissions of the token used for this request. Only reachable when authenticated with an API token (boot token or admin token). Responses: 200, 401, 403.
PUT /auth/admin-tokens/{id}/permissions. Update admin token permissions. Update the permission scope of an existing admin API token (admin only) Parameters: id. Body: permissions. Responses: 200, 400, 401, 403, 500.
DELETE /auth/admin-tokens/{id}. Delete admin token. Permanently delete an admin API token (admin only) Parameters: id. Responses: 200, 400, 401, 403, 500.
PUT /auth/admin-tokens/{id}/deactivate. Deactivate admin token. Deactivate an admin API token without deleting it (admin only) Parameters: id. Responses: 200, 400, 401, 403, 500.
Disks. Disk and Storage Management
GET /disks. List all disks with partitions. Retrieve a comprehensive list of all disks with their partitions and power status. Uses live data without caching. Parameters: performance, skipStandby. Responses: 200, 401, 500.
GET /disks/{device}/usage. Get disk usage statistics. Retrieve usage statistics for a specific disk or partition using df command Parameters: device. Responses: 200, 401, 500.
GET /disks/{device}/power. Get disk power status. Retrieve the current power status of a specific disk Parameters: device. Responses: 200, 401, 500.
GET /disks/{device}/iostats. Get disk I/O statistics. Retrieve I/O statistics for a specific disk Parameters: device. Responses: 200, 401, 500.
POST /disks/{device}/wake. Wake disk from standby. Wake a disk from standby or sleep mode (admin only) Parameters: device. Responses: 200, 401, 403, 500.
POST /disks/{device}/sleep. Put disk to sleep/standby. Put a disk into standby or sleep mode (admin only) Parameters: device. Body: mode. Responses: 200, 400, 401, 403, 500.
GET /disks/{device}/smart. Get SMART information. Retrieve comprehensive SMART data for a specific disk. Data is sourced from smartd state files (no disk I/O) or smartctl (live). If the disk is sleeping, all SMART fields are null unless wakeUp=true is specified. Response structure is always consistent - fields are null when unavailable. Parameters: device, wakeUp. Responses: 200, 401, 500.
GET /disks/descriptions/orphaned. List orphaned disk descriptions. Get all disk descriptions whose disk is no longer physically present Responses: 200, 500.
DELETE /disks/descriptions/orphaned. Delete all orphaned disk descriptions. Remove all descriptions whose disk is no longer physically present (admin only) Responses: 200, 403, 500.
DELETE /disks/descriptions/orphaned/{serial}. Delete a specific orphaned disk description. Remove a single description by serial number, only if the disk is not currently present (admin only) Parameters: serial. Responses: 200, 403, 404, 500.
PUT /disks/{device}/description. Set or clear a disk description. Set a user-defined description for a disk. The description is stored persistently keyed by the disk's serial number (survives device name changes). An empty or null description removes the entry. The config file is only written on change (admin only). Parameters: device. Body: description. Responses: 200, 400, 403, 500.
GET /disks/availablefilesystems. Get available filesystems. Retrieve a simple array of available filesystem names for formatting. Use the pooltype parameter to filter filesystems based on pool type: - multi : Returns only btrfs and zfs (if available) - these support multiple disks - nonraid , single , mergerfs or no parameter: Returns all available filesystems Parameters: pooltype. Responses: 200, 401, 500.
POST /disks/format. Format disk/device. Format a disk or device with specified filesystem (admin only) Body: device, filesystem, partition, wipeExisting, preClear. Responses: 200, 400, 401, 403, 500.
POST /disks/{device}/preclear/abort. Abort preClear operation. Abort a running preClear operation on a device (admin only). The disk will be left in an undefined state. Parameters: device. Responses: 200, 400, 401, 403, 500.
POST /disks/{device}/partition. Create partition. Create a new partition on the specified device (admin only) Parameters: device. Responses: 200, 401, 403, 500.
DELETE /disks/{device}/partition/{partitionNumber}. Delete partition. Delete a specific partition from a device (admin only) Parameters: device, partitionNumber. Responses: 200, 401, 403, 500.
DELETE /disks/{device}/wipe. Wipe entire disk. Completely wipe a disk, removing all partitions and data (admin only) Parameters: device. Responses: 200, 401, 403, 500.
GET /disks/{device}/partitions. Get disk partitions. Retrieve all partitions for a specific disk Parameters: device. Responses: 200, 401, 500.
POST /disks/wake. Wake multiple disks. Wake multiple disks from standby simultaneously (admin only) Body: devices. Responses: 200, 400, 401, 403, 500.
POST /disks/sleep. Sleep multiple disks. Put multiple disks to sleep/standby simultaneously (admin only) Body: devices, mode. Responses: 200, 400, 401, 403, 500.
POST /disks/power/status. Get power status for multiple disks. Get power status for multiple disks simultaneously (admin only) Body: devices. Responses: 200, 400, 401, 403, 500.
POST /disks/power/manage. Manage disk power settings. Configure power management settings for a disk (admin only) Body: device, check. Responses: 200, 400, 401, 403, 500.
GET /disks/unassigned. List unassigned disks. Retrieve a list of disks that are not assigned to any pool or array and are not system disks Parameters: includePerformance, skipStandby. Responses: 200, 401, 500.
POST /disks/{device}/mount. Mount a disk device. Mount a single disk device or partition to /mnt/disks/ with automatic mountability checks (admin only) Parameters: device. Body: mountOptions. Responses: 200, 400, 401, 403, 500.
POST /disks/{device}/unmount. Unmount a disk device. Unmount a single disk device or partition, handles BTRFS multi-device properly (admin only) Parameters: device. Body: force, lazy. Responses: 200, 401, 403, 500.
GET /disks/zram/ramdisks. Get ZRAM ramdisk devices. Returns all active ZRAM ramdisk devices (type=ramdisk, enabled=true) that can be used as storage pools Responses: 200, 401, 500.
SMART. SMART Monitoring Configuration and Status
GET /disks/smart/config. Get SMART monitoring configuration. Retrieve the complete SMART monitoring configuration including defaults, per-disk settings, and orphaned entries Responses: 200, 500.
PUT /disks/smart/config. Update global SMART configuration. Update global SMART settings (defaults, smartdOptions). Supports partial updates via deep merge - only send the fields you want to change. After update, smartd.conf is regenerated and smartd reloaded. Note: Use the per-disk endpoints to manage individual disk configurations. Body: defaults, smartdOptions. Responses: 200, 400, 403, 500.
GET /disks/smart/config/disks/{device}. Get SMART config for a specific disk. Retrieve the monitoring configuration for a disk by device name (e.g. sda) or serial number Parameters: device. Responses: 200, 404, 500.
PUT /disks/smart/config/disks/{device}. Update SMART config for a specific disk. Update monitoring settings for a specific disk by device name or serial. Supports partial updates - only send the fields you want to change. After update, smartd.conf is regenerated. Parameters: device. Body: temperatureWarning, temperatureCritical, monitoredAttributes, attributeNotificationCooldown. Responses: 200, 400, 403, 404, 500.
DELETE /disks/smart/config/disks/{device}. Delete disk SMART config. Remove custom configuration for a disk by device name or serial. The disk will be re-added with default settings on the next sync if still present. Parameters: device. Responses: 200, 403, 404, 500.
POST /disks/smart/config/disks/{device}/acknowledge. Acknowledge current SMART errors for a disk. Acknowledge the current raw values of a disk's monitored SMART attributes as a baseline. Unlike removing an attribute from monitoring ("ignore"), acknowledged errors stay visible (the disk keeps warning=true) but no further boot/live notifications are sent until a value rises above its acknowledged baseline. Values are taken from the cached smartd state (no disk wakeup). Send an empty body to acknowledge all currently reported attributes, or { attributes: [187] } to acknowledge a specific attribute at its current value (no number needed). A baseline can also be cleared inline by sending "" or null for an attribute under "acknowledged"; to clear baselines explicitly use DELETE on the same path. Parameters: device. Body: attributes, acknowledged. Responses: 200, 400, 403, 404, 500.
DELETE /disks/smart/config/disks/{device}/acknowledge. Clear acknowledged SMART errors for a disk. Remove acknowledgement baselines for a disk. Send an empty body to clear all baselines, or { attributes: [...] } to clear only specific attribute IDs. After clearing, the normal boot/live notification behaviour applies again for those attributes. Parameters: device. Body: attributes. Responses: 200, 400, 403, 404, 500.
GET /disks/smart/config/orphaned. List orphaned disk entries. Get all disk configurations that were previously known but the disk is no longer physically present Responses: 200, 500.
DELETE /disks/smart/config/orphaned. Delete all orphaned entries. Remove all orphaned disk configuration entries at once Responses: 200, 403, 500.
DELETE /disks/smart/config/orphaned/{serial}. Delete a specific orphaned entry. Remove a single orphaned disk configuration entry by serial number Parameters: serial. Responses: 200, 403, 404, 500.
Disks WebSocket. Real-time disk monitoring via WebSocket
GET /disks/websocket/stats. Get Disks WebSocket monitoring statistics. Responses: 200, 401, 500.
GET /disks/websocket/events. Disks WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time disk monitoring. Connection: Connect to WebSocket at /disks namespace with path /api/v1/socket.io/ Events to emit (client β server): - subscribe-disks: Subscribe to disk throughput and temperature updates - unsubscribe-disks: Unsubscribe from disk updates - get-disks: Get immediate disk data (one-time) Events to listen for (server β client): - disks-update: Real-time throughput data (every 2s) - disks-temperature-update: Temperature data (every 10s if includeTemperature=true) - disks-subscription-confirmed: Subscription confirmation - disks-unsubscription-confirmed: Unsubscription confirmation - error: Error messages Important Notes: - Standby disks are NOT woken up for temperature queries - Throughput comes from /proc/diskstats (no disk wake-up) - Temperature uses smartctl -n standby (safe for standby disks) Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/disks', { path: '/api/v1/socket.io/' }); Subscribe to all disks with temperature: socket.emit('subscribe-disks', { token: 'your-jwt-token', devices: [], // empty = all disks includeTemperature: true }); Subscribe to specific disks: socket.emit('subscribe-disks', { token: 'your-jwt-token', devices: ['sda', 'sdb'], includeTemperature: false }); Listen for updates: socket.on('disks-update', (data) = { console.log('Throughput:', data.throughput); }); socket.on('disks-temperature-update', (data) = { console.log('Temperatures:', data.temperatures); }); Responses: 200.
Pools. Storage Pool Management
GET /pools/vpools. List all vpools (MergerFS Path Pools). List all MergerFS Path Pools with mount status and storage info. Storage is reported from a single df on the mergerfs union mount, like regular pools. Responses: 200, 500.
POST /pools/vpools. Create a vpool (MergerFS Path Pool). Create a new MergerFS Path Pool by unioning existing filesystem paths under /mnt/{name}. The name must be globally unique (across pools and vpools) and must not be a reserved name. When automount is enabled (default), the pool is mounted immediately; all configured paths must exist as directories. Body: name, paths, automount, comment, config. Responses: 201, 400, 403.
PUT /pools/vpools/order. Update vpool display order. Update the display order (index) of vpools (admin only) Body: order. Responses: 200, 400, 500.
GET /pools/vpools/{id}. Get a vpool by ID. Parameters: id. Responses: 200, 404.
DELETE /pools/vpools/{id}. Delete a vpool by ID. Unmount (if mounted) and remove the vpool from vpools.json. Source paths are never deleted. Fails if the pool is in use unless force is set (admin only). Parameters: id. Body: force. Responses: 200, 400, 404.
POST /pools/vpools/{id}/mount. Mount a vpool by ID. Mount the mergerfs union at /mnt/{name}. All configured source paths are validated first; if any path is missing or not a directory, the mount is aborted with an error. Parameters: id. Responses: 200, 400, 404.
POST /pools/vpools/{id}/unmount. Unmount a vpool by ID. Unmount the mergerfs union at /mnt/{name}. Source paths are left untouched. Parameters: id. Body: force. Responses: 200, 400, 404.
POST /pools/vpools/{id}/automount. Toggle automount for a vpool. Enable or disable automount (flag only, does not mount/unmount) (admin only) Parameters: id. Body: enabled. Responses: 200, 400, 500.
GET /pools. List all pools. Get a list of all storage pools with optional filtering, performance and temperature data Parameters: type, exclude_type, includeMetrics. Responses: 200, 500.
GET /pools/availablepooltypes. Get available pool types. Retrieve a simple array of available pool types. Responses: 200, 401, 500.
GET /pools/{id}. Get pool by ID. Get a specific pool by its ID Parameters: id. Responses: 200, 404.
DELETE /pools/{id}. Remove pool by ID. Remove a storage pool Parameters: id. Responses: 200, 404.
GET /pools/{id}/status. Get pool status. Get the current status of a pool Parameters: id. Responses: 200, 404, 500.
POST /pools/{id}/automount. Toggle automount setting for a pool. Enable or disable automatic mounting of a pool on system boot (admin only) Parameters: id. Body: enabled. Responses: 200, 400, 404, 500.
POST /pools/{id}/shared. Toggle shared mount propagation for a pool. Enable or disable shared mount propagation (mount --make-shared / --make-private) live without remounting; the setting is persisted and reapplied on mount (admin only) Parameters: id. Body: enabled. Responses: 200, 400, 404, 500.
PATCH /pools/{id}/comment. Update pool comment. Update the comment/description for a storage pool (admin only) Parameters: id. Body: comment. Responses: 200, 400, 404, 500.
GET /pools/{id}/config. Get pool configuration. Retrieve the configuration settings for a specific pool Parameters: id. Responses: 200, 404, 500.
PATCH /pools/{id}/config. Update pool configuration. Update configuration settings for a pool (works for all pool types - mergerfs, btrfs, xfs, etc.) Supports dot-notation for nested properties: - Direct: { "unclean check": false } - Nested: { "sync.enabled": true, "sync.schedule": "0 5 " } Parameters: id. Body: unclean_check, encrypted, raid_level, shared, sync.enabled, sync.schedule, usage_alert.warning, usage_alert.alert, spindown. Responses: 200, 404, 500.
PUT /pools/order. Update order of all pools. Update the display order for multiple pools at once by providing an array of pool IDs with their new index values (admin only) Body: order. Responses: 200, 400, 500.
POST /pools/single. Create single device pool. Create a new single device pool Body: name, device, filesystem, format, config, passphrase, options. Responses: 201, 400, 403.
POST /pools/multi. Create multi-device BTRFS pool. Create a new multi-device BTRFS pool Body: name, devices, raidLevel, format, config, passphrase, options. Responses: 201, 400, 403.
POST /pools/mergerfs. Create MergerFS pool. Create a new MergerFS pool Body: name, devices, filesystem, format, config, passphrase, options, skip_size_check. Responses: 201, 400, 403.
POST /pools/bcachefs. Create bcachefs pool. Creates a bcachefs pool. bcachefs is a native multi-device filesystem, so redundancy is a configuration property instead of a dedicated parity disk and parity devices stays empty. Redundancy maps to RAID levels as follows: - data replicas: 1 - striping without redundancy (RAID 0) - data replicas: 2 - mirroring (RAID 1/10) - data replicas: 2 + erasure code: true - single parity (RAID 5) - data replicas: 3 + erasure code: true - double parity (RAID 6) Cache devices are passed separately and get the ssd device group, data devices get hdd. Requires the bcachefs kernel module from the mos-bcachefs plugin. Body: name, devices, cache_devices, format, config, passphrase, options. Responses: 201, 400, 403.
POST /pools/nonraid. Create NonRAID pool. Create a new NonRAID pool with optional parity devices (max 2). Important: - Only one NonRAID pool per system - Parity check runs automatically after creation unless parity valid is true - When parity valid is true, parity is marked as valid and no check runs Body: name, devices, filesystem, format, parity, parity_valid, config, passphrase, options. Responses: 201, 400, 403.
POST /pools/nonraid/replace. Replace devices in a NonRAID pool. Replace one or more devices in the NonRAID pool with parity reconstruction (admin only). Important: - Only one NonRAID pool can exist per system - Pool must be unmounted before replacement - Maximum replacements: 1 device with 1 parity, 2 devices with 2 parities - Data and parity devices can be replaced simultaneously - Parity reconstruction starts automatically after replacement Size Requirements: - New data devices must be <= smallest parity device - New parity devices must be = largest data device Encryption: - Passphrase required when replacing data devices in encrypted pools - New data devices will be encrypted with the existing key Body: replacements, format, passphrase. Responses: 200, 400, 403, 404, 500.
POST /pools/nonraid/adddevice. Add data device to NonRAID pool. Add a new data device to the NonRAID pool (admin only). Device will be assigned the next available slot (1-28) automatically. Modes: - format: true - Create partition and format device with specified filesystem - format: false - Import existing partition/filesystem (device must have usable filesystem) Important: - Pool must be unmounted before adding device - Not possible while a parity operation (check, clear, rebuild) is running - Pool is mounted automatically after the device was added - With parity and format: true the disk is cleared (zeroed) in the background first, then formatted and added to the pool. The array stays usable; notifications are sent on start and when the disk is ready - format: false runs a parity check unless parity valid is true - parity valid: true skips clearing/check (disk must already be zeroed) - Passphrase required for encrypted pools without keyfile - Adding, replacing or adding parity is rejected until a new disk is cleared, formatted and ready Size Requirements: - New data device must be <= smallest parity device Body: device, format, filesystem, passphrase, parity_valid. Responses: 200, 400, 404, 500.
POST /pools/nonraid/addparity. Add parity device to NonRAID pool. Add a new parity device to the NonRAID pool (admin only). Device will be assigned the next available parity slot (1 or 2) automatically. Important: - Pool must be unmounted before adding parity - Not possible while a parity operation (check, clear, rebuild) is running - Pool is mounted automatically after the parity was added - Maximum 2 parity devices allowed - Parity check ALWAYS runs when adding parity - Parity device is NOT formatted Size Requirements: - Parity device must be = largest data device Body: device, passphrase. Responses: 200, 400, 404, 500.
POST /pools/{id}/mount. Mount pool by ID. Mount a storage pool Parameters: id. Body: passphrase, mountOptions, mount_missing. Responses: 200, 404.
POST /pools/{id}/unmount. Unmount pool by ID. Unmount a storage pool Parameters: id. Body: force. Responses: 200, 404.
POST /pools/{id}/devices. Add devices to pool. Add new devices to an existing pool Parameters: id. Body: devices, format, group. Responses: 200, 404.
POST /pools/{id}/parity/add. Add parity devices to a MergerFS pool. Add one or more parity devices to an existing MergerFS pool for SnapRAID protection (admin only). Devices will be formatted if needed and SnapRAID configuration will be updated. Parameters: id. Body: devices, format, skip_size_check. Responses: 200, 400, 404, 500.
POST /pools/{id}/parity/replace. Replace a parity device in a MergerFS pool. Replace an existing parity device with a new one in a MergerFS pool (admin only). The old device will be unmounted and the new device will take over its parity slot. SnapRAID configuration will be updated automatically. Size Requirements (default): - New parity device must be = largest data device - Use skip size check to bypass this validation Encryption: - For encrypted pools, the new device will be encrypted with the existing key - Passphrase is required for encrypted pools Parameters: id. Body: oldDevice, newDevice, format, passphrase, skip_size_check. Responses: 200, 400, 404, 500.
POST /pools/{id}/parity/remove. Remove parity devices from a MergerFS pool. Remove one or more parity devices from an existing MergerFS pool (admin only). If all parity devices are removed, SnapRAID configuration will be cleaned up. Parameters: id. Body: devices, unmount. Responses: 200, 400, 404, 500.
POST /pools/{id}/devices/remove. Remove devices from an existing pool. Remove one or more devices from an existing MergerFS, BTRFS or bcachefs pool (admin only). Will update SnapRAID config if pool has SnapRAID configured. bcachefs: The pool must be mounted. Data is evacuated onto the remaining devices before removal, which can take hours on large devices, so it runs in the background and notifications are sent on start and completion. The remaining devices must still satisfy data replicas/erasure coding, and the last cache device cannot be removed while a cache mode is configured. Only one device operation per bcachefs pool can run at a time. Parameters: id. Body: devices, unmount. Responses: 200, 400, 401, 403, 404, 500.
POST /pools/{id}/devices/add. Add devices to an existing pool. Add one or more devices to an existing pool (admin only). BTRFS Pools: - Single-device pools (type 'btrfs') will automatically be converted to multi-device with raid1 configuration - Uses native BTRFS device addition functionality - Pool must be mounted for the operation MergerFS Pools: - Devices will be mounted individually and added to the MergerFS union - Will format devices if needed and update SnapRAID config if pool has SnapRAID configured - Pool will be remounted automatically after device addition bcachefs Pools: - Devices join the mounted filesystem online, format must be true - group selects data (hdd) or cache (ssd), cache durability follows the pool's cache mode Parameters: id. Body: devices, format, passphrase, group. Responses: 200, 400, 401, 403, 404, 500.
POST /pools/{id}/devices/replace. Replace a device in a pool. Replace a data device of a BTRFS, MergerFS or bcachefs pool (admin only). bcachefs Pools: - The pool must be mounted and format must be true - The new device joins first in the group of the old one, then the old device is evacuated and removed, so redundancy never drops during the replacement - The old device must still be reachable, evacuation can take hours on large devices and runs in the background, notifications are sent on start and completion Parameters: id. Body: oldDevice, newDevice, format, passphrase. Responses: 200, 404, 500.
POST /pools/{id}/parity. Execute parity operation on a MergerFS or NonRAID pool. Execute parity operations on pools with parity devices (admin only). MergerFS Pools (SnapRAID): - Operations: sync, check, scrub, fix, status, force stop NonRAID Pools: - Operations: check, pause, resume, cancel, auto - For 'check': use 'option' parameter (CORRECT or NOCORRECT) - 'auto': Automatically starts check (NOCORRECT) if not running, or cancels if running Parameters: id. Body: operation, option, fixDisks. Responses: 200, 400, 404, 500.
POST /pools/{id}/btrfs/scrub. Execute BTRFS scrub operation. Scrub operations for BTRFS pools only. Operations: - start: Start a new scrub (fails if one is already running) - status: Get current scrub status and progress - pause: Pause a running scrub (via cancel in BTRFS) - cancel: Cancel a running scrub Parameters: id. Body: operation. Responses: 200, 400, 404, 500.
POST /pools/{id}/btrfs/balance. Execute BTRFS balance operation. Balance operations for BTRFS pools only. Operations: - start: Start a new balance (optionally with RAID conversion) - status: Get current balance status and progress - pause: Pause a running balance - cancel: Cancel a running or paused balance Parameters: id. Body: operation, raidLevel. Responses: 200, 400, 404, 500.
POST /pools/{id}/bcachefs/scrub. Execute bcachefs scrub operation. Scrub operations for bcachefs pools only. A scrub verifies all data checksums and repairs from redundant copies where possible; affected paths are logged to dmesg. Operations: - start: Start a new scrub (fails if one is already running) - status: Get current scrub status and progress - cancel: Stop a running scrub (bcachefs has no pause) Parameters: id. Body: operation. Responses: 200, 400, 404, 500.
Pools WebSocket. Real-time pool monitoring via WebSocket
GET /pools/websocket/stats. Get WebSocket monitoring statistics. Responses: 200, 401, 500.
GET /pools/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time pool monitoring. Connection: Connect to WebSocket at /api/v1/pools namespace Events to emit (client β server): - subscribe-pools: Subscribe to pool updates with filters - unsubscribe-pools: Unsubscribe from pool updates - get-pools: Get immediate pool data (one-time) Events to listen for (server β client): - pools-update: Real-time pool data updates - pools-performance-update: Real-time I/O throughput (if includePerformance=true, every 2s) - pools-error: Error messages - pools-subscription-confirmed: Subscription confirmation - pools-unsubscription-confirmed: Unsubscription confirmation - error: General error messages Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/pools', { path: '/socket.io/' }); Subscribe to all MergerFS pools: socket.emit('subscribe-pools', { token: 'your-jwt-token', interval: 30000, filters: { type: 'mergerfs' } }); Listen for updates: socket.on('pools-update', (data) = { console.log('Pools updated:', data.pools); }); Responses: 200.
iSCSI Targets. iSCSI Target Management
GET /iscsi/targets. Get all iSCSI targets. Retrieve all configured iSCSI targets (admin only) Responses: 200, 401, 403, 500.
POST /iscsi/targets. Create new iSCSI target. Create a new iSCSI target (admin only) Body: id, name, iqn, portal, authentication, luns, initiators. Responses: 201, 400, 401, 403, 500.
GET /iscsi/targets/info. Get iSCSI targets statistics. Retrieve statistical information about iSCSI targets (admin only) Responses: 200, 401, 403, 500.
GET /iscsi/targets/{targetId}. Get a specific iSCSI target. Retrieve detailed information about a specific iSCSI target by ID (admin only) Parameters: targetId. Responses: 200, 400, 401, 403, 404, 500.
PUT /iscsi/targets/{targetId}. Update an iSCSI target. Update configuration of an existing iSCSI target (admin only) Parameters: targetId. Body: name, portal, authentication, luns, initiators. Responses: 200, 400, 401, 403, 404, 500.
DELETE /iscsi/targets/{targetId}. Delete an iSCSI target. Delete an existing iSCSI target (admin only) Parameters: targetId, deleteImages. Responses: 200, 400, 401, 403, 404, 500.
POST /iscsi/targets/restart. Restart all iSCSI targets. Restart/reload all configured iSCSI targets (admin only) Responses: 200, 401, 403, 500.
POST /iscsi/targets/{targetId}/luns. Add a LUN to an iSCSI target. Add a new LUN to an existing iSCSI target (admin only) Parameters: targetId. Body: id, path, backing_store, mode, size. Responses: 201, 400, 401, 403, 404, 500.
PUT /iscsi/targets/{targetId}/luns/{lunId}. Update a LUN in an iSCSI target. Update configuration of an existing LUN in an iSCSI target (admin only) Parameters: targetId, lunId. Body: path, backing_store, mode, size. Responses: 200, 400, 401, 403, 404, 500.
DELETE /iscsi/targets/{targetId}/luns/{lunId}. Remove a LUN from an iSCSI target. Remove an existing LUN from an iSCSI target (admin only) Parameters: targetId, lunId, deleteImages. Responses: 200, 400, 401, 403, 404, 500.
iSCSI Initiators. iSCSI Initiator Management
GET /iscsi/initiator. Get iSCSI initiator configuration. Retrieve the complete iSCSI initiator configuration (admin only) Responses: 200, 401, 403, 500.
PUT /iscsi/initiator/name. Update initiator name. Update the IQN name of the iSCSI initiator (admin only) Body: name. Responses: 200, 400, 401, 403, 500.
POST /iscsi/initiator/targets. Add a new target. Add a new iSCSI target to the initiator configuration (admin only) Body: name, portal, connection. Responses: 201, 400, 401, 403, 500.
GET /iscsi/initiator/targets/{targetId}. Get a specific target. Retrieve detailed information about a specific target by ID (admin only) Parameters: targetId. Responses: 200, 400, 401, 403, 404, 500.
PUT /iscsi/initiator/targets/{targetId}. Update a target. Update configuration of an existing target (admin only) Parameters: targetId. Body: name, portal, connection. Responses: 200, 400, 401, 403, 404, 500.
DELETE /iscsi/initiator/targets/{targetId}. Remove a target. Remove an existing target from the initiator configuration (admin only) Parameters: targetId. Responses: 200, 400, 401, 403, 404, 500.
POST /iscsi/initiator/test-connection. Test connection to a target. Test connectivity to an iSCSI target using discovery (admin only) Body: targetIp, targetPort. Responses: 200, 400, 401, 403, 500.
POST /iscsi/initiator/targets/{targetId}/logout. Logout from a target. Logout from an iSCSI target session (admin only) Parameters: targetId. Responses: 200, 400, 401, 403, 404, 500.
POST /iscsi/initiator/targets/{targetId}/login. Login to a target. Login to an iSCSI target session (admin only) Parameters: targetId. Responses: 200, 400, 401, 403, 404, 500.
Docker. Docker Container Management
POST /docker/mos/create. Create new container from template. Create a new Docker container from a provided template (admin only) Body: name, image, ports, volumes, environment, restart, no_autoupdate. Responses: 200, 400, 401, 403, 500.
DELETE /docker/mos/remove. Remove container and its template. Remove a Docker container and its associated template (admin only) Body: name. Responses: 200, 400, 401, 403, 404, 500.
GET /docker/mos/containers. Get Docker images with update status. Retrieve all Docker images/containers with their update availability status (admin only) Parameters: performance. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/containers. Update Docker container indices. Update the ordering indices for Docker containers (admin only) Responses: 200, 400, 401, 403, 404, 500.
GET /docker/mos/containers/calc. Get container image sizes. Get a list of all Docker containers with their image names and sizes, sorted by size descending (admin only) Responses: 200, 401, 403, 500.
GET /docker/mos/containers/{name}/calc. Get a single container image size. Get a Docker container with its image name and size (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
GET /docker/mos/ports. Get Docker container port bindings. Retrieve all host port bindings from all Docker containers with container name, protocol and status (admin only) Responses: 200, 401, 403, 500.
POST /docker/mos/update_check. Check for Docker updates. Check for available updates for Docker containers (admin only) Body: name. Responses: 200, 401, 403, 500.
POST /docker/mos/upgrade. Upgrade containers. Upgrade Docker containers to their latest versions (admin only) Body: name, force_update. Responses: 200, 401, 403, 500.
POST /docker/mos/xml_convert. Convert XML using URL. Convert XML template from URL to Docker container configuration (admin only) Body: url. Responses: 200, 400, 401, 403, 500.
GET /docker/mos/templates. Get all container templates (installed and removed). Retrieve all Docker container templates with status flags (admin only) Responses: 200, 401, 403, 500.
GET /docker/mos/templates/{name}. Get specific container template. Retrieve a specific Docker container template, preferring installed over removed if both exist (admin only) Parameters: name, edit. Responses: 200, 400, 401, 403, 404, 500.
DELETE /docker/mos/templates/{name}. Permanently delete a removed container template. Delete a template from the removed directory (admin only). Only works on removed templates, not installed ones. Parameters: name. Responses: 200, 400, 401, 403, 404, 500.
DELETE /docker/mos/templates/removed. Permanently delete all removed container templates. Delete all templates from the removed directory at once (admin only). Only works on removed templates, not installed ones. Responses: 200, 401, 403, 500.
GET /docker/mos/groups. Get all container groups. Responses: 200, 401, 500.
POST /docker/mos/groups. Create a new container group. Body: name, containers, icon. Responses: 201, 400, 401, 500.
PUT /docker/mos/groups/{groupId}. Update container group (name, icon, containers). Update any combination of group properties in a single request Parameters: groupId. Body: name, icon, containers, addContainers, removeContainers. Responses: 200, 400, 404, 500.
DELETE /docker/mos/groups/{groupId}. Delete a container group. Parameters: groupId. Responses: 200, 401, 404, 500.
PUT /docker/mos/groups/order. Update group order/index. Responses: 200, 400, 401, 500.
POST /docker/mos/groups/{groupId}/start. Start all containers in a group. Start all containers that belong to the specified group. Note: Docker Compose groups are not supported - use the compose API endpoints instead. Parameters: groupId. Responses: 200, 400, 404, 500.
POST /docker/mos/groups/{groupId}/stop. Stop all containers in a group. Stop all containers that belong to the specified group. Note: Docker Compose groups are not supported - use the compose API endpoints instead. Parameters: groupId. Responses: 200, 400, 404, 500.
POST /docker/mos/groups/{groupId}/restart. Restart all containers in a group. Restart all containers that belong to the specified group (stop and start sequentially). Note: Docker Compose groups are not supported - use the compose API endpoints instead. Parameters: groupId. Responses: 200, 400, 404, 500.
POST /docker/mos/groups/{groupId}/upgrade. Upgrade all containers in a group. Upgrade all containers that belong to the specified group to their latest versions (sequential execution). Note: This endpoint waits for all upgrades to complete before returning. For live streaming output during the upgrade process, use the WebSocket API with operation: 'upgrade-group'. WebSocket Alternative: socket.emit('docker', { token: 'your-jwt-token', operation: 'upgrade-group', params: { groupId: '123', force update: false } }); Docker Compose: Compose groups are not supported - use the compose API endpoints instead. Parameters: groupId. Body: force_update. Responses: 200, 400, 404, 500.
GET /docker/mos/unusedimages. Get unused Docker images. Get list of Docker images that are not used by any container (admin only) Responses: 200, 401, 500.
DELETE /docker/mos/unusedimages. Delete unused Docker images. Delete unused Docker images - all or specific ones by ID (admin only) Responses: 200, 400, 401, 500.
GET /docker/{path}. Docker REST API Proxy (GET). Proxy requests to the Docker REST API via Unix socket (admin only) Parameters: path. Responses: 200, 401, 403, 500.
POST /docker/{path}. Docker REST API Proxy (POST). Proxy POST requests to the Docker REST API via Unix socket (admin only) Parameters: path. Responses: 200, 401, 403, 500.
PUT /docker/{path}. Docker REST API Proxy (PUT). Proxy PUT requests to the Docker REST API via Unix socket (admin only) Parameters: path. Responses: 200, 401, 403, 500.
DELETE /docker/{path}. Docker REST API Proxy (DELETE). Proxy DELETE requests to the Docker REST API via Unix socket (admin only) Parameters: path. Responses: 200, 204, 401, 403, 500.
Docker Compose. Docker Compose Stack Management
GET /docker/mos/compose/stacks. Get all compose stacks. Retrieve all Docker Compose stacks (admin only) Parameters: performance. Responses: 200, 401, 403, 500.
POST /docker/mos/compose/stacks. Create a new compose stack. Create and deploy a new Docker Compose stack (admin only) Body: name, yaml, env, icon, autostart, webui, web_ui_url. Responses: 201, 400, 401, 403, 500.
GET /docker/mos/compose/stacks/{name}. Get a specific compose stack. Retrieve details of a specific Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
PUT /docker/mos/compose/stacks/{name}. Update a compose stack. Update an existing Docker Compose stack (admin only) Parameters: name. Body: yaml, env, icon, autostart, webui, web_ui_url. Responses: 200, 400, 401, 403, 404, 500.
PATCH /docker/mos/compose/stacks/{name}. Update stack settings. Update stack settings (like autostart, webui) without redeploying (admin only) Parameters: name. Body: autostart, webui, web_ui_url. Responses: 200, 401, 403, 404, 500.
DELETE /docker/mos/compose/stacks/{name}. Delete a compose stack. Stop and delete a Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/start. Start a compose stack. Start all services in a Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/stop. Stop a compose stack. Stop all services in a Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/restart. Restart a compose stack. Restart all services in a Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/pull. Pull images for a compose stack. Pull latest images for all services in a Docker Compose stack (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/sync-shas. Sync local SHAs to remote SHAs for a compose stack. Updates the compose-containers file with current local image SHAs after a pull (admin only) Parameters: name. Responses: 200, 401, 403, 404, 500.
POST /docker/mos/compose/stacks/{name}/upgrade. Upgrade a compose stack to latest images. Pulls latest images and redeploys the stack (admin only) Parameters: name. Body: force_update. Responses: 200, 401, 403, 404, 500.
GET /docker/mos/compose/templates. Get all compose template names. Retrieve all Docker Compose template names grouped by installed and removed (admin only) Responses: 200, 401, 403, 500.
GET /docker/mos/compose/templates/{name}. Get specific compose template. Retrieve a specific Docker Compose template, preferring installed over removed if both exist (admin only) Parameters: name, edit. Responses: 200, 400, 401, 403, 404, 500.
DELETE /docker/mos/compose/templates/{name}. Permanently delete a removed compose stack template. Delete a stack template from the removed directory (admin only). Only works on removed stacks, not installed ones. Parameters: name. Responses: 200, 400, 401, 403, 404, 500.
DELETE /docker/mos/compose/templates/removed. Permanently delete all removed compose stack templates. Delete all stack templates from the removed directory at once (admin only). Only works on removed stacks, not installed ones. Responses: 200, 401, 403, 500.
Docker WebSocket. Real-time Docker operations via WebSocket
GET /docker/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time Docker operations. Connection: Connect to WebSocket at /api/v1/docker namespace Simplified Event System: Events to emit (client β server): - docker - Start a Docker operation (pull, upgrade, upgrade-group, create, check-updates, compose-create, compose-update, compose-pull, compose-delete, compose-upgrade) - docker-cancel - Cancel an ongoing operation - docker-get-operations - Get list of active operations - docker-stats-subscribe - Subscribe to live container statistics stream - docker-stats-unsubscribe - Unsubscribe from container statistics stream Event to listen for (server β client): - docker-update - ONE event for ALL updates (status-based) Status values in docker-update: - started - Operation has started - running - Operation is running (contains output field with live data) - completed - Operation completed (contains success and duration) - cancelled - Operation was cancelled - error - Error occurred (contains message) - operations-list - Response to docker-get-operations (contains operations[]) Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/docker', { path: '/api/v1/socket.io/' }); Pull a Docker image (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'pull', params: { image: 'nginx:latest' } }); Note: Pull is only available via WebSocket (no REST alternative) Listen for ALL updates with ONE event: socket.on('docker-update', (data) = { const { status, operationId, output, message } = data; switch(status) { case 'started': console.log(Started: ${operationId}); break; case 'running': console.log('Output:', output); // Live output break; case 'completed': console.log(data.success ? 'β Success' : 'β Failed'); break; case 'cancelled': console.log('Operation cancelled'); break; case 'error': console.error('Error:', message); break; } }); Upgrade all containers in a group (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'upgrade-group', params: { groupId: '1695384000123', force update: false } }); REST Alternative: POST /api/v1/docker/mos/groups/{groupId}/upgrade (waits for completion, no streaming) Upgrade a single container (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'upgrade', params: { name: 'nginx', force update: false } }); REST Alternative: POST /api/v1/docker/mos/upgrade (waits for completion, no streaming) Create a container (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'create', params: { template: { name: 'my-nginx', repo: 'nginx:latest', ports: [{ host: '8080', container: '80' }], // ... full template like REST endpoint } } }); REST Alternative: POST /api/v1/docker/mos/create (waits for completion, no streaming) Check for updates (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'check-updates', params: { name: 'nginx' } // or omit for all containers }); REST Alternative: POST /api/v1/docker/mos/update check (waits for completion, no streaming) Docker Compose Operations: Create a compose stack (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'compose-create', params: { name: 'my-stack', yaml: 'version: "3"\\nservices:\\n ...', env: 'ENV VAR=value', // optional icon: 'https://example.com/icon.png' // optional } }); REST Alternative: POST /api/v1/docker/mos/compose/stacks (waits for completion, no streaming) Update a compose stack (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'compose-update', params: { name: 'my-stack', yaml: 'version: "3"\\nservices:\\n ...', env: 'ENV VAR=new value', // optional icon: 'https://example.com/new-icon.png' // optional } }); REST Alternative: PUT /api/v1/docker/mos/compose/stacks/{name} (waits for completion, no streaming) Pull images for a compose stack (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'compose-pull', params: { name: 'my-stack' } }); REST Alternative: POST /api/v1/docker/mos/compose/stacks/{name}/pull (waits for completion, no streaming) Delete a compose stack (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'compose-delete', params: { name: 'my-stack' } }); REST Alternative: DELETE /api/v1/docker/mos/compose/stacks/{name} (waits for completion, no streaming) Upgrade a compose stack (with live streaming): socket.emit('docker', { token: 'your-jwt-token', operation: 'compose-upgrade', params: { name: 'my-stack', force update: false } }); REST Alternative: POST /api/v1/docker/mos/compose/stacks/{name}/upgrade (waits for completion, no streaming) Subscribe to live container stats (continuous streaming): socket.emit('docker-stats-subscribe', { token: 'your-jwt-token', params: { name: 'nginx' } }); Note: Stream runs continuously until unsubscribe or disconnect Listen for stats updates: socket.on('docker-update', (data) = { if (data.status === 'running' && data.stats) { const { stats } = data; // Pre-calculated stats with human formatting console.log('CPU:', stats.cpu percent + '%'); console.log('Memory:', stats.memory usage human, '/', stats.memory limit human, (${stats.memory percent}%)); console.log('Network:', stats.network rx human, 'β', stats.network tx human, 'β', (${stats.network total human} total)); console.log('Block I/O:', stats.block read human, 'read', stats.block write human, 'write', (${stats.block total human} total)); console.log('PIDs:', stats.pids); // Raw byte values: memory usage, network rx, block read, etc. // Memory always binary (GiB/MiB), network/block uses user's byte format preference // Stats update every ~1 second } }); Unsubscribe from stats stream: socket.emit('docker-stats-unsubscribe', { token: 'your-jwt-token', operationId: 'stats-nginx-1234567890-abc123' }); Note: All stats streams are automatically stopped on disconnect Get active operations after reconnect: socket.emit('docker-get-operations', { token: 'your-jwt-token' }); socket.on('docker-update', (data) = { if (data.status === 'operations-list') { console.log('Active operations:', data.operations); // Client is automatically joined to operation rooms } }); Cancel an operation: socket.emit('docker-cancel', { token: 'your-jwt-token', operationId: 'pull-1234567890-abc123' }); Key Features: - Operations run in background (disconnect doesn't kill process) - Only explicit docker-cancel stops the operation - Multiple clients can watch same operation via rooms - Reconnect and resume with docker-get-operations - Container stats streams continuously until unsubscribe/disconnect - Multiple clients can monitor the same container simultaneously Responses: 200.
GET /docker/websocket/stats. Get WebSocket operation statistics. Get statistics about active Docker operations via WebSocket (Admin only) Responses: 200, 401, 500.
LXC. LXC Container Management
GET /lxc/containers. List all LXC Containers. Parameters: performance. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/start. Start a container. Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/stop. Stop a container. Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/restart. Restart a container. Stops the container, waits 1 second, then starts it again Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/kill. Forcefully stop a container (kill). Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/freeze. Freeze (pause) a container. Pauses all processes in the container. The container must be running. Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/{name}/unfreeze. Unfreeze (resume) a container. Resumes all processes in a frozen container. Parameters: name. Responses: 200, 401, 403, 500.
POST /lxc/containers/create. Create a new LXC container. Responses: 200, 400, 401, 403, 500.
GET /lxc/images. Get available container images/distributions. Lists all available distributions, their releases and supported architectures. Data is cached for 1 hour. Responses: 200, 401, 403, 500.
GET /lxc/containers/{name}/mounts. List host bind mounts of a container. Parameters: name. Responses: 200.
POST /lxc/containers/{name}/mounts. Add host bind mount(s) to a container. Appends mounts (single object or array), deduping by source+destination. Applied on next container start. Parameters: name. Responses: 200.
PUT /lxc/containers/{name}/mounts. Replace all host bind mounts of a container. Replaces the full set of mounts with the provided array. Applied on next container start. Parameters: name. Responses: 200.
DELETE /lxc/containers/{name}/mounts. Remove specific host bind mount(s) from a container. Removes mounts matched by source+destination (single object or array). Applied on next container start. Parameters: name. Responses: 200.
DELETE /lxc/containers/{name}. Destroy (delete) a container. Parameters: name, force. Responses: 200, 400, 401, 403, 500.
GET /lxc/containers/usage. Get resource usage for all containers. Returns detailed resource usage information including CPU percentage, memory usage, and IP addresses for all containers. Data is sorted by container name. CPU and memory data is only collected for running containers. Responses: 200, 401, 403, 500.
GET /lxc/mos/containers. Get container startup order. Retrieves the current startup order, autostart setting, and description for all LXC containers. Containers are sorted by their index value. Responses: 200, 401, 403, 500.
POST /lxc/mos/containers. Update container startup order. Updates the startup order, autostart setting, and/or description for multiple LXC containers. Modifies Responses: 200, 400, 401, 403, 500.
GET /lxc/backups. List all containers with their backups. Returns all containers with their backups. Includes orphaned backups (containers that no longer exist). Containers without backups have an empty backups array. Responses: 200.
GET /lxc/containers/{name}/backups. List backups for a specific container. Returns backups for a specific container. Returns empty array if no backups exist. Parameters: name. Responses: 200.
POST /lxc/containers/{name}/backups. Create a backup of a container. Starts an async backup operation. Container will be stopped during backup (unless use snapshot is enabled). Parameters: name. Body: use_snapshot, compression, threads. Responses: 200, 400, 500.
POST /lxc/containers/{name}/backups/abort. Abort an active backup operation. Parameters: name. Responses: 200, 400.
DELETE /lxc/containers/{name}/backups/{filename}. Delete a specific backup file. Parameters: name, filename. Responses: 200, 400.
POST /lxc/containers/{name}/backups/restore. Restore a container from backup. Starts an async restore operation. If new name matches existing container, it will be replaced. Parameters: name. Body: backup_file, new_name. Responses: 200, 400.
POST /lxc/containers/{name}/convert-btrfs. Convert container rootfs to BTRFS subvolume. Converts a dir-based container to use a BTRFS subvolume. LXC directory must be on BTRFS filesystem. Parameters: name. Responses: 200, 400.
GET /lxc/snapshots. List all containers with their snapshots. Returns all containers with their snapshots. Containers without snapshots have an empty snapshots array. Responses: 200.
GET /lxc/containers/{name}/snapshots. List all snapshots for a container. Returns snapshots for a specific container. Returns empty array if no snapshots exist. Parameters: name. Responses: 200.
POST /lxc/containers/{name}/snapshots. Create a snapshot of a container. Parameters: name. Responses: 200, 400.
DELETE /lxc/containers/{name}/snapshots/{snapshot}. Delete a snapshot. Parameters: name, snapshot. Responses: 200, 400.
POST /lxc/containers/{name}/snapshots/{snapshot}/restore. Restore container from a snapshot. Restores the container to the state of the specified snapshot. Container will be stopped during restore. Parameters: name, snapshot. Responses: 200, 400.
POST /lxc/containers/{name}/snapshots/{snapshot}/clone. Create a new container from a snapshot. Creates a new container based on the specified snapshot. Parameters: name, snapshot. Body: new_name. Responses: 200, 400.
GET /lxc/containers/{name}/calc. Calculate container rootfs size. Recursively calculates the total size of a container's rootfs and returns it in human-readable format based on user byte format preference (admin only) Parameters: name. Responses: 200, 400, 401, 403, 500.
LXC WebSocket. Real-time LXC container monitoring via WebSocket
GET /lxc/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time LXC container usage monitoring. Connection: Connect to WebSocket at /api/v1/lxc namespace Events to emit (client β server): - subscribe-container-usage: Subscribe to container usage updates (all or single via name param) - unsubscribe-container-usage: Unsubscribe from container usage updates - get-container-usage: Get immediate container usage data (one-time) - get-lxc-containers: Get all containers with full details (one-time, like GET /lxc/containers) Events to listen for (server β client): - container-usage-update: Real-time container usage data (every ~2s) - lxc-containers-update: Full container details (response to get-lxc-containers) - container-usage-subscription-confirmed: Subscription confirmation - container-usage-unsubscription-confirmed: Unsubscription confirmation - error: General error messages Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/lxc', { path: '/api/v1/socket.io/' }); Subscribe to all containers: socket.emit('subscribe-container-usage', { token: 'your-jwt-token' }); Subscribe to single container: socket.emit('subscribe-container-usage', { token: 'your-jwt-token', name: 'webserver' }); Listen for updates: socket.on('container-usage-update', (data) = { console.log('Container usage:', data.containers); }); Responses: 200.
GET /lxc/websocket/stats. Get LXC WebSocket statistics. Returns current statistics for the LXC container usage WebSocket Responses: 200, 503.
VM. Virtual Machine Management with libvirt/QEMU
GET /vm/machines. List all virtual machines. Retrieve a list of all virtual machines with their status, disk information and VNC ports (admin only) Parameters: performance. Responses: 200, 401, 403, 500.
POST /vm/machines. Create a new virtual machine. Create a new VM with the specified configuration. Disks are automatically created if they don't exist and a size is specified. Body: name, icon, description, memory, cpus, cpuPins, hugepages, platform, bios, disks, cdroms, networks, graphics, hostdevices, usbdevices. Responses: 200, 400, 500.
GET /vm/machines/usage. Get resource usage for all VMs. Returns CPU usage (%) and memory usage (GiB) for all VMs. Running VMs show actual usage from cgroup2, stopped VMs show 0 values. Takes ~1 second to measure CPU if any VM is running. Responses: 200, 500.
POST /vm/machines/{name}/start. Start a virtual machine. Start a stopped virtual machine by name (admin only) Parameters: name. Responses: 200, 401, 403, 500.
POST /vm/machines/{name}/stop. Stop a virtual machine (graceful shutdown). Gracefully shutdown a running virtual machine by sending ACPI shutdown signal (admin only) Parameters: name. Responses: 200, 401, 403, 500.
POST /vm/machines/{name}/kill. Kill a virtual machine (force stop). Forcefully terminate a running virtual machine without graceful shutdown (admin only). Use this when normal stop doesn't work. Parameters: name. Responses: 200, 401, 403, 500.
POST /vm/machines/{name}/restart. Restart a virtual machine (graceful reboot). Gracefully reboot a running virtual machine by sending ACPI reboot signal (admin only) Parameters: name. Responses: 200, 401, 403, 500.
POST /vm/machines/{name}/reset. Reset a virtual machine (hard reset). Forcefully reset a running virtual machine without graceful shutdown, like pressing the reset button (admin only) Parameters: name. Responses: 200, 401, 403, 500.
GET /vm/machines/{name}/autostart. Get autostart status of a virtual machine. Retrieve whether a virtual machine is configured to start automatically on system boot (admin only) Parameters: name. Responses: 200, 401, 403, 500.
PUT /vm/machines/{name}/autostart. Set autostart status for a virtual machine. Enable or disable automatic startup of a virtual machine on system boot (admin only) Parameters: name. Body: enabled. Responses: 200, 400, 401, 403, 500.
GET /vm/machinetypes. Get available QEMU machine types. Returns list of available machine types (pc-i440fx and pc-q35 only). Sorted with i440fx alias first, then i440fx versions descending, then q35 alias, then q35 versions descending. Responses: 200.
GET /vm/capabilities. Get VM capabilities. Returns available BIOS types, disk options, network options, and machine types Responses: 200.
GET /vm/binfmt_architectures. Get available binfmt architectures. Returns a list of available architectures for binfmt misc emulation. These are determined by installed qemu- -static binaries in /usr/bin. Use these values in the binfmt architectures field when updating system settings. Responses: 200, 401, 403, 500.
DELETE /vm/machines/{name}. Delete a virtual machine. Delete a VM and optionally remove its disk files. NVRAM is kept by default to preserve TPM/UEFI state. Parameters: name, removeDisks, removeNvram. Responses: 200, 500.
GET /vm/index. Get VM index. Returns the synchronized VM index with name, index, icon and description for each VM Responses: 200, 500.
PUT /vm/index. Update VM index. Update index, icon and/or description for one or more VMs Responses: 200, 400, 500.
GET /vm/machines/{name}/xml. Get raw VM XML. Returns the libvirt XML configuration for a VM wrapped in JSON Parameters: name. Responses: 200.
PUT /vm/machines/{name}/xml. Update VM XML directly. Replace the VM's XML configuration. VM must be stopped. Parameters: name, validate. Body: xml. Responses: 200, 400, 500.
POST /vm/xml/validate. Validate VM XML. Validate XML without applying it Body: xml. Responses: 200.
GET /vm/machines/{name}/config. Get simplified VM configuration. Returns parsed VM configuration in a simplified format Parameters: name. Responses: 200.
PUT /vm/machines/{name}/config. Update VM with simplified configuration. Update VM configuration using simplified format. VM must be stopped. Parameters: name. Body: memory, cpus, hugepages, platform, bios, disks, networks, graphics. Responses: 200, 500.
GET /vm/machines/{name}/calc. Calculate VM disk sizes. Calculates the total disk usage for a VM, including all attached disks (file-based and block devices). File-based disks use actual (sparse-aware) size. CD-ROMs are excluded. Parameters: name. Responses: 200, 401, 403, 404, 500.
GET /vm/virtioiso/versions. Get available VirtIO ISO versions. Fetches the list of all available VirtIO driver versions from the Fedora archive Responses: 200, 500.
GET /vm/virtioiso/installed. Get installed VirtIO ISOs. Lists all VirtIO driver ISOs that are currently installed Responses: 200, 500.
POST /vm/virtioiso/download. Download a VirtIO ISO. Starts a background download of the specified VirtIO driver version. A notification is sent when complete. Body: version. Responses: 200, 400, 500.
POST /vm/virtioiso/cleanup. Cleanup old VirtIO ISOs. Deletes all installed VirtIO ISOs except the newest version Responses: 200, 500.
POST /vm/vnc/token. Generate VNC access token. Generates a short-lived token for WebSocket VNC connection to a running VM Body: vmName. Responses: 200, 400, 500.
GET /vm/vnc/sessions. Get active VNC sessions. Returns all active VNC sessions (admin only) Responses: 200.
VM WebSocket. Real-time VM monitoring via WebSocket
GET /vm/websocket/stats. Get VM WebSocket statistics. Returns current statistics for the VM usage WebSocket Responses: 200, 401, 500.
GET /vm/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time VM usage monitoring. Connection: Connect to WebSocket at /api/v1/vm namespace Events to emit (client β server): - subscribe-vm-usage: Subscribe to VM usage updates (all VMs or single VM via name param) - unsubscribe-vm-usage: Unsubscribe from VM usage updates - get-vm-usage: Get immediate VM usage data (one-time) - get-vm-machines: Get all VMs with full details (one-time, like GET /vm/machines) Events to listen for (server β client): - vm-usage-update: Real-time VM usage data (every ~2s, includes 1s CPU measurement) - vm-machines-update: Full VM details (response to get-vm-machines) - vm-usage-subscription-confirmed: Subscription confirmation - vm-usage-unsubscription-confirmed: Unsubscription confirmation - error: General error messages Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/vm', { path: '/api/v1/socket.io/' }); Subscribe to VM usage updates: socket.emit('subscribe-vm-usage', { token: 'your-jwt-token' }); Listen for updates: socket.on('vm-usage-update', (data) = { data.vms.forEach(vm = { console.log(${vm.name}: ${vm.state}); if (vm.state === 'running') { console.log( CPU: ${vm.cpu.usage}%); console.log( RAM: ${vm.memory.formatted}); } }); }); Unsubscribe: socket.emit('unsubscribe-vm-usage', { token: 'your-jwt-token' }); Responses: 200.
Users. SMB Users and System User Management
PUT /users/root. Change root password. Change the password for the system root user (admin only) Body: password. Responses: 200, 400, 401, 403, 500.
GET /users. Get users (admin sees all, user sees only themselves). Retrieve users - admins can see all users, normal users only see their own profile (both return arrays) Responses: 200, 401, 500.
GET /users/me. Get own user profile. Retrieve the authenticated user's own profile information Responses: 200, 401, 404, 500.
PUT /users/me. Update own user profile. Update the authenticated user's own profile (limited fields for normal users) Body: language, primary_color, darkmode, menu_layout, byte_format, hide_inactive_menus, group_menus, password. Responses: 200, 400, 401, 404, 500.
GET /users/{id}. Get specific user (admin only). Retrieve information about a specific user by ID (admin only) Parameters: id. Responses: 200, 401, 403, 404, 500.
PUT /users/{id}. Update user (admin only for other users). Update user information - admins can update any user, normal users redirected to /users/me Parameters: id. Body: username, role, language, primary_color, darkmode, menu_layout, byte_format, password. Responses: 200, 400, 401, 403, 404, 500.
DELETE /users/{id}. Delete user (admin only). Delete a specific user from the system (admin only) Parameters: id. Responses: 200, 401, 403, 404, 500.
Shares. Network Shares Management (SMB/CIFS)
GET /shares. Get all shares configuration. Retrieve all network shares configuration (admin only) Responses: 200, 401, 403, 500.
GET /shares/smb. Get SMB shares only. Retrieve only SMB/CIFS shares configuration (admin only) Responses: 200, 401, 403, 500.
POST /shares/smb. Create new SMB share. Create a new SMB/CIFS network share (admin only). Pool-based shares : Provide poolName and a relative subPath. The directory will be created if it doesn't exist, and ownership/permissions will be set. Absolute path shares : Set poolName to null and provide an absolute path in subPath. The directory must already exist, and ownership/permissions will NOT be modified. For MergerFS pools : You can specify targetDevices to control which disk slots store the data. Use GET /pools to get available disk slots from pool.data devices[].slot. Body: shareName, poolName, subPath, automount, enabled, read_only, guest_ok, browseable, write_list, valid_users, force_root, create_mask, directory_mask, inherit_permissions, hide_dot_files, preserve_case, case_sensitive, allow_execute_always, comment. Responses: 201, 400, 401, 403, 500.
GET /shares/nfs. Get NFS shares only. Retrieve only NFS shares configuration (admin only) Responses: 200, 401, 403, 500.
POST /shares/nfs. Create new NFS share. Create a new NFS network share (admin only). Pool-based shares : Provide poolName and a relative subPath. The directory will be created if it doesn't exist, and ownership/permissions will be set. Absolute path shares : Set poolName to null and provide an absolute path in subPath. The directory must already exist, and ownership/permissions will NOT be modified. For MergerFS pools : You can specify targetDevices to control which disk slots store the data. Use GET /pools to get available disk slots from pool.data devices[].slot. Body: shareName, poolName, subPath, source, enabled, read_only, anonuid, anongid, write_operations, mapping, secure, createDirectory, targetDevices, createDirectories, managePathRules. Responses: 201, 400, 401, 403, 500.
GET /shares/info. Get shares information/statistics. Retrieve statistical information about all network shares (admin only) Responses: 200, 401, 403, 500.
GET /shares/pools. Get available pools for share creation. Retrieve a list of storage pools available for creating network shares (admin only) Responses: 200, 401, 403, 500.
GET /shares/smb/{shareId}. Get a specific SMB share. Retrieve detailed information about a specific SMB share by ID (admin only) Parameters: shareId. Responses: 200, 400, 401, 403, 500.
PUT /shares/smb/{shareId}. Update a SMB share. Update configuration of an existing SMB share (admin only). Note : When updating targetDevices, the corresponding path rules in the pool configuration are automatically updated. Parameters: shareId. Body: enabled, read_only, guest_ok, browseable, write_list, valid_users, allow_execute_always, comment, targetDevices. Responses: 200, 400, 401, 403, 500.
DELETE /shares/smb/{shareId}. Delete a SMB share. Delete an existing SMB share and optionally its directory (admin only). Pool-based shares : Directory can be deleted if deleteDirectory is true. Absolute path shares : Directory will NEVER be deleted, even if deleteDirectory is true (to protect external directories). Note : Associated path rules in the pool configuration are automatically removed when removePathRule is true (default). Parameters: shareId. Body: deleteDirectory, removePathRule. Responses: 200, 400, 401, 403, 500.
GET /shares/smb/{shareId}/target-devices. Get target devices for a specific share. Retrieve the current target devices (disk slots) configuration for a share. Only applies to MergerFS pools. Parameters: shareId. Responses: 200, 404, 500.
PUT /shares/smb/{shareId}/target-devices. Update target devices for a share. Update the target devices (disk slots) for a specific share. This automatically manages the path rules in the pool configuration. Only works with MergerFS pools. Parameters: shareId. Body: targetDevices. Responses: 200, 400, 404, 500.
DELETE /shares/smb/{shareId}/target-devices. Remove target devices from a share. Remove target devices configuration from a share. This removes the path rule from both the share and pool configuration. Parameters: shareId. Responses: 200, 404, 500.
GET /shares/nfs/{shareId}. Get a specific NFS share. Retrieve detailed information about a specific NFS share by ID (admin only) Parameters: shareId. Responses: 200, 401, 403, 404, 500.
PUT /shares/nfs/{shareId}. Update a NFS share. Update configuration of an existing NFS share (admin only). Note : When updating targetDevices, the corresponding path rules in the pool configuration are automatically updated. Parameters: shareId. Body: source, enabled, read_only, anonuid, anongid, write_operations, mapping, secure, targetDevices. Responses: 200, 400, 401, 403, 404, 500.
DELETE /shares/nfs/{shareId}. Delete a NFS share. Delete an existing NFS share and optionally its directory (admin only). Pool-based shares : Directory can be deleted if deleteDirectory is true. Absolute path shares : Directory will NEVER be deleted, even if deleteDirectory is true (to protect external directories). Note : Associated path rules in the pool configuration are automatically removed when removePathRule is true (default). Parameters: shareId. Body: deleteDirectory, removePathRule. Responses: 200, 400, 401, 403, 404, 500.
GET /shares/nfs/{shareId}/target-devices. Get target devices for a specific NFS share. Retrieve the current target devices (disk slots) configuration for an NFS share. Only applies to MergerFS pools. Parameters: shareId. Responses: 200, 404, 500.
PUT /shares/nfs/{shareId}/target-devices. Update target devices for a NFS share. Update the target devices (disk slots) for a specific NFS share. This automatically manages the path rules in the pool configuration. Only works with MergerFS pools. Parameters: shareId. Body: targetDevices. Responses: 200, 400, 404, 500.
DELETE /shares/nfs/{shareId}/target-devices. Remove target devices from a NFS share. Remove target devices configuration from an NFS share. This removes the path rule from both the share and pool configuration. Parameters: shareId. Responses: 200, 404, 500.
Remotes. Remote Shares Management (SMB/NFS Mount)
GET /remotes. List all remote shares. Responses: 200, 401, 403, 500.
POST /remotes. Create new remote share. Body: name, type, server, share, username, password, domain, version, uid, gid, auto_mount. Responses: 201, 400, 401, 403, 409, 500.
GET /remotes/{id}. Get remote share by ID. Parameters: id. Responses: 200, 401, 403, 404, 500.
PUT /remotes/{id}. Update remote share. Parameters: id. Body: name, type, server, share, username, password, domain, version, uid, gid, auto_mount. Responses: 200, 400, 401, 403, 404, 409, 500.
DELETE /remotes/{id}. Delete remote share. Delete a remote share. If the remote is currently mounted, it will be automatically unmounted before deletion. Parameters: id. Responses: 200, 401, 403, 404, 500.
POST /remotes/{id}/mount. Mount remote share. Parameters: id. Responses: 200, 401, 403, 404, 409, 500.
POST /remotes/{id}/unmount. Unmount remote share. Parameters: id. Responses: 200, 401, 403, 404, 409, 500.
GET /remotes/{id}/status. Get remote share mount status. Parameters: id. Responses: 200, 401, 403, 404, 500.
POST /remotes/listshares. List all available shares from a server. Discover all available shares from a remote server without saving credentials. For SMB, username and password are optional (uses guest access if not provided). For NFS, only server address is needed. Body: server, type, username, password, domain. Responses: 200, 400, 401, 403, 500.
POST /remotes/connectiontest. Test connection to remote share without saving. Test connection to a remote share. Body: type, server, share, username, password, domain. Responses: 200, 400, 401, 403, 500.
Cron. Cron Jobs Management
GET /cron. Get all cron jobs. Retrieve a list of all cron jobs in the system (available to all authenticated users) Responses: 200, 401, 500.
POST /cron. Create new cron job. Create a new scheduled cron job (admin only) Body: name, schedule, command, enabled, script, scriptPath, convert_to_unix. Responses: 201, 400, 401, 403, 500.
GET /cron/scripts. List all cron scripts. Retrieve a list of all available scripts in /boot/optional/scripts/cron (admin only) Responses: 200, 401, 403, 500.
GET /cron/scripts/{scriptName}. Get cron script content. Retrieve the content and metadata of a specific cron script (admin only) Parameters: scriptName. Responses: 200, 401, 403, 404, 500.
PUT /cron/scripts/{scriptName}. Update cron script content. Update the content of an existing cron script (admin only) Parameters: scriptName. Body: content. Responses: 200, 400, 401, 403, 404, 500.
DELETE /cron/scripts/{scriptName}. Delete cron script. Delete a cron script (admin only, only if not used by any cron job) Parameters: scriptName, deleteDependentJobs. Responses: 200, 400, 401, 403, 404, 500.
GET /cron/system. Get system cron jobs. Retrieve all system cron jobs from crontab that are marked with " MOS" comments (admin only) Responses: 200, 401, 403, 500.
GET /cron/{identifier}. Get specific cron job. Retrieve a specific cron job by ID or name (available to all authenticated users) Parameters: identifier. Responses: 200, 401, 404, 500.
PUT /cron/{identifier}. Update cron job. Update an existing cron job by ID or name (admin only) Parameters: identifier. Body: name, schedule, command, enabled, script, scriptPath, convert_to_unix. Responses: 200, 400, 401, 403, 404, 500.
DELETE /cron/{identifier}. Delete cron job. Delete an existing cron job by ID or name (admin only) Parameters: identifier, delete_script. Responses: 200, 401, 403, 404, 500.
POST /cron/{identifier}/enable. Enable cron job. Enable a disabled cron job (admin only) Parameters: identifier. Responses: 200, 401, 403, 404, 500.
POST /cron/{identifier}/disable. Disable cron job. Disable an enabled cron job (admin only) Parameters: identifier. Responses: 200, 401, 403, 404, 500.
POST /cron/{identifier}/start. Start cron job manually. Start a cron job manually in the background (admin only, checks if already running) Parameters: identifier. Responses: 200, 400, 401, 403, 404, 500.
POST /cron/{identifier}/stop. Stop running cron job. Stop a currently running cron job (admin only) Parameters: identifier. Responses: 200, 400, 401, 403, 404, 500.
System. System Information, Monitoring and Power Management
GET /system/memory. Get detailed memory information. Retrieve detailed memory information with separate dirty cache tracking (available to all authenticated users) Responses: 200, 401, 500.
GET /system/detailed. Get detailed system information. Retrieve comprehensive system information including OS, CPU, memory, disks, network and processes (admin only) Responses: 200, 401, 403, 500.
GET /system/load. Get system load, temperature, memory and network utilization. Retrieve current system load, temperature information including per-core metrics, detailed memory usage with installed/reserved memory and services breakdown (Docker/LXC/VMs/ZRAM), and network utilization for all interfaces (available to all authenticated users) Responses: 200, 401, 500.
POST /system/power/reboot. Reboot system. Perform a system reboot (admin only). The system will shutdown and restart. Responses: 200, 401, 403, 500.
POST /system/power/shutdown. Shutdown system. Perform a graceful system shutdown (admin only). The system will halt after shutting down all services. Responses: 200, 401, 403, 500.
GET /system/proxy. Get proxy settings. Retrieve current proxy configuration from /boot/config/system/proxy.json (admin only) Responses: 200, 401, 403, 500.
PUT /system/proxy. Update proxy settings. Update proxy configuration in /boot/config/system/proxy.json. Supports partial updates - you can update individual fields or all at once (admin only) Body: http_proxy, https_proxy, ftp_proxy, no_proxy. Responses: 200, 400, 401, 403, 500.
GET /system/keymaps. List available keymaps. Retrieve a list of all available keyboard layouts/keymaps (admin only) Responses: 200, 401, 403, 500.
GET /system/timezones. List available timezones. Retrieve a list of all available system timezones (admin only) Responses: 200, 401, 403, 500.
GET /system/governors. Get available CPU governors. Get list of available CPU frequency governors from the system (admin only) Responses: 200, 401, 403, 500.
GET /system/logs. List all log files. Retrieve a simple array of log file paths in /var/log recursively. Excludes empty files (admin only) Responses: 200, 401, 403, 500.
GET /system/logs/content. Read log file content. Read content of a specific log file from /var/log. Supports reading from start or end of file (admin only) Parameters: path, lines, tail. Responses: 200, 400, 401, 403, 404, 500.
GET /system/devices/pci. Get PCI devices information. Retrieve detailed information about all PCI devices by parsing lspci output. Data Structure: - Basic device info comes from lspci -vmm -nn (structured, reliable) - Detailed hierarchical data comes from lspci -vvv -nn (parsed by indentation) Details Object: The details object contains a hierarchical structure where: - Keys from lspci output become object properties - Values are either strings, objects with nested properties, or arrays (for duplicate keys) - Lines without keys are stored in raw arrays - Structure follows the indentation hierarchy of lspci output This format is fully generic and automatically adapts to any changes in lspci output. (Admin only) Responses: 200, 401, 403, 500.
GET /system/devices/usb. Get USB devices information. Retrieve detailed information about all USB devices by parsing lsusb output. Data Structure: - Basic device info comes from lsusb (bus, device, vendor id, product id, description) - Detailed hierarchical data comes from lsusb -v (parsed by indentation) Details Object: The details object contains a hierarchical structure where: - Keys from lsusb output become object properties - Values are either strings, objects with nested properties, or arrays (for duplicate keys) - Structure follows the indentation hierarchy of lsusb output - Elements with children have a value property containing the header line This format is fully generic and automatically adapts to any changes in lsusb output. (Admin only) Responses: 200, 401, 403, 500.
GET /system/gpus. Get GPU information. Returns information about all GPUs in the system grouped by vendor (Intel, AMD, NVIDIA) Responses: 200, 401, 403, 500.
GET /system/sensors. Get hardware sensor data. Retrieve hardware sensor data from lm-sensors (temperatures, voltages, fan speeds, etc.) Responses: 200, 401, 500.
GET /system/timedate. Get current system date and time. Retrieve the current system date and time Responses: 200, 401, 500.
PUT /system/timedate. Set system date and/or time. Set the system date and/or time. At least one of date or time must be provided. Requires admin privileges. Body: date, time. Responses: 200, 400, 401, 403, 500.
System Load WebSocket. Real-time system load monitoring via WebSocket
GET /system/websocket/stats. Get WebSocket monitoring statistics. Responses: 200, 401, 500.
GET /system/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time system load monitoring. Connection: Connect to WebSocket at /api/v1/system namespace Events to emit (client β server): - subscribe-load: Subscribe to system load updates - unsubscribe-load: Unsubscribe from system load updates - get-load: Get immediate system load data (one-time) Events to listen for (server β client): - load-update: Real-time system data updates with different keys at different intervals: - cpu: CPU load data (every 1s) - memory: Memory and uptime data (every 8s) - network: Network interface statistics (every 2s) - pools: Pools with performance data per disk (initial + every 2s) - poolsTemperatures: Disk temperatures only (every 10s) - load-subscription-confirmed: Subscription confirmation with intervals - load-unsubscription-confirmed: Unsubscription confirmation - error: General error messages Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/system', { path: '/socket.io/' }); Subscribe to system load updates (pools always included): socket.emit('subscribe-load', { token: 'your-jwt-token' }); Listen for updates and merge by key: socket.on('load-update', (data) = { if (data.cpu) updateCpu(data.cpu); if (data.memory) updateMemory(data.memory); if (data.network) updateNetwork(data.network); if (data.pools) updatePools(data.pools); if (data.poolsTemperatures) updatePoolTemperatures(data.poolsTemperatures); }); Responses: 200.
MOS. MOS System Configuration and Settings Management
GET /mos/settings/docker. Get Docker settings. Retrieve current Docker service configuration (admin only) Responses: 200, 401, 403, 404, 500.
POST /mos/settings/docker. Update Docker settings. Update Docker service configuration (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/settings/lxc. Get LXC settings. Retrieve current LXC service configuration (admin only) Responses: 200, 401, 403, 404, 500.
POST /mos/settings/lxc. Update LXC settings. Update LXC service configuration (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/settings/vm. Get VM settings. Retrieve current VM service configuration (admin only) Responses: 200, 401, 403, 404, 500.
POST /mos/settings/vm. Update VM settings. Update VM service configuration (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/system/network/interfaces. Detect physical network interfaces. Scans the system for all physical network interfaces and returns their MAC addresses, link state, and speed. With include=tun, tun/wireguard interfaces (Tailscale, Netbird, WireGuard) are appended. This is a read-only system endpoint without reconciliation (admin only) Parameters: include. Responses: 200, 401, 500.
POST /mos/settings/network/interfaces/reconcile. Reconcile network interfaces. Matches detected physical interfaces against stored config by MAC address. Updates kernel names, marks orphaned interfaces, and adds new interfaces with DHCP (admin only) Responses: 200, 401, 500.
GET /mos/settings/network/interfaces. Get network interfaces. Retrieve current network interfaces configuration (admin only) Responses: 200, 401, 403, 500.
POST /mos/settings/network/interfaces. Update network interfaces. Update network interfaces configuration (admin only). Supports ethernet, bridge, bond types with MAC identification, MTU, and MAC spoofing. Responses: 200, 400, 401, 403, 500.
POST /mos/settings/network/apply. Confirm pending network changes. Confirms pending network changes within the 60-second timeout window. If not called in time, changes are automatically rolled back to the previous configuration. Must be called after any network interface change (update interfaces, add/delete VLAN). Responses: 200, 400, 401, 403, 500.
POST /mos/settings/network/revert. Revert pending network changes. Immediately reverts pending network changes to the previous configuration and restarts networking. Can be used instead of waiting for the automatic rollback timeout. Responses: 200, 400, 401, 403, 500.
POST /mos/settings/network/interfaces/{interfaceName}/vlans. Add VLAN to interface. Add a new VLAN to a network interface (admin only) Parameters: interfaceName. Body: vlan_id, ipv4, ipv6, mtu. Responses: 200, 400, 500.
DELETE /mos/settings/network/interfaces/{interfaceName}/vlans/{vlanId}. Delete VLAN from interface. Delete a VLAN from a network interface (admin only) Parameters: interfaceName, vlanId. Responses: 200, 400, 500.
GET /mos/settings/network/services. Get network services. Retrieve current network services configuration (admin only) Responses: 200, 401, 403, 500.
POST /mos/settings/network/services. Update network services. Update network services configuration (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/settings/network/services/rsync/config. Get rsync daemon configuration. Read the rsyncd.conf stored in /boot/config/system/rsync/rsyncd.conf (admin only) Responses: 200, 401, 403, 404, 500.
POST /mos/settings/network/services/rsync/config. Update rsync daemon configuration. Writes the rsyncd.conf to /boot/config/system/rsync/rsyncd.conf, creating the directory and the file if they do not exist yet. When the content actually changed and the rsync daemon service is enabled, the daemon is stopped and started again. Body: content, create_backup. Responses: 200, 400, 401, 403, 500.
GET /mos/settings/network/services/samba/config. Get Samba extra configuration. Read the Samba extra configuration files stored in /boot/config/system/samba/ (admin only). Returns global extra.conf and shares extra.conf content. Responses: 200, 401, 403, 500.
POST /mos/settings/network/services/samba/config. Update Samba extra configuration. Writes the Samba extra configuration files to /boot/config/system/samba/, creating the directory and files if they do not exist yet. Only provided fields are written. When any content actually changed and the samba service is enabled, the smbd daemon is restarted. If samba discovery is also enabled, nmbd and wsddn are restarted as well. Null values are treated as empty strings. Body: global, shares, create_backup. Responses: 200, 400, 401, 403, 500.
GET /mos/settings/system. Get system settings. Retrieve current system configuration (admin only) Responses: 200, 401, 403, 404, 500.
POST /mos/settings/system. Update system settings. Update system configuration including hostname, global spindown, keymap, timezone, NTP, notification sounds, and CPU frequency settings (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/settings/notifications/providers. Get all notification providers. Retrieve all notification provider configurations (admin only) Responses: 200, 401, 403, 500.
POST /mos/settings/notifications/providers. Create a new notification provider. Create a new notification provider configuration (admin only). The name "email" is reserved. Body: name, enabled, user, token, url, method, headers, body, alert_mapping, color_prio. Responses: 201, 400, 409, 500.
GET /mos/settings/notifications/providers/{name}. Get a single notification provider. Retrieve a specific notification provider configuration by name (admin only) Parameters: name. Responses: 200, 400, 404, 500.
PATCH /mos/settings/notifications/providers/{name}. Update a notification provider. Partially update a notification provider configuration (admin only) Parameters: name. Body: enabled, user, token, url, method, headers, body, alert_mapping, color_prio. Responses: 200, 400, 404, 500.
DELETE /mos/settings/notifications/providers/{name}. Delete a notification provider. Delete a notification provider configuration (admin only) Parameters: name. Responses: 200, 400, 404, 500.
GET /mos/settings/notifications/email. Get email notification provider config. Retrieve the email notification provider configuration (admin only) Responses: 200, 401, 403, 500.
POST /mos/settings/notifications/email. Update email notification provider config. Create or update the email notification provider configuration (admin only) Body: enabled, smtp_host, smtp_port, smtp_tls, smtp_user, smtp_password, from, to, subject, body, alert_mapping. Responses: 200, 400, 500.
POST /mos/update_api. Update the API service. Update the API service immediately - useful after API updates (admin only) Responses: 200, 401, 403, 500.
POST /mos/update_ui. Update the UI service (nginx). Update the UI service (nginx) immediately (admin only) Responses: 200, 401, 403, 500.
POST /mos/recreatecerts. Recreate SSL certificates. Recreates SSL certificates via nginx recreatecerts and restarts nginx (admin only) Responses: 200, 401, 403, 500.
GET /mos/certificates. Get SSL certificate information. Returns validity, subject, issuer, fingerprint and expiry information for the nginx and root CA certificates (admin only) Responses: 200, 401, 403, 500.
GET /mos/services. Get all service status. Retrieve current status of all MOS services including Docker, LXC, VM and network services in flat structure (admin only) Responses: 200, 401, 403, 500.
POST /mos/restart/service. Restart generic service. Restart generic service immediately - supports 'api' and 'nginx' (admin only) Body: service. Responses: 200, 400, 401, 403, 500.
POST /mos/updateos. Update MOS. Initiate OS update using mos-os update script (admin only) Body: version, channel, update_kernel, update_plugins. Responses: 200, 400, 401, 403, 500.
POST /mos/rollbackos. Rollback MOS. Initiate OS rollback using mos-os update rollback mos script (admin only) Body: kernel_rollback. Responses: 200, 400, 401, 403, 500.
GET /mos/getreleases. Get available MOS releases. Retrieve available releases grouped by channel (alpha, beta, stable) using mos-os get releases script (admin only) Responses: 200, 401, 403, 500.
GET /mos/osinfo. Get current MOS and CPU information. Retrieve current OS release information from /etc/mos-release.json combined with CPU details and hostname (admin only) Responses: 200, 401, 403, 500.
GET /mos/getkernel. Get available kernel releases. Retrieve available kernel releases sorted by version (newest first) using mos-kernel getreleases script (admin only) Responses: 200, 401, 403, 500.
GET /mos/getdrivers. Get available driver releases. Retrieve available driver releases grouped by category using mos-drivers get releases script (admin only) Parameters: kernelVersion, excludeinstalled. Responses: 200, 401, 403, 500.
GET /mos/installeddrivers. Get installed drivers. Retrieve installed drivers from /boot/optional/drivers/ for the current running kernel grouped by category (admin only) Responses: 200, 401, 403, 500.
POST /mos/drivers. Download or upgrade drivers. Download a specific driver (using complete packagename OR drivername+driverversion) or check for driver updates using mos-driver download script (admin only) Responses: 200, 400, 401, 403, 500.
DELETE /mos/drivers. Delete a driver. Delete a specific driver package from /boot/optional/drivers/ (admin only) Responses: 200, 400, 401, 403, 404, 500.
POST /mos/updatekernel. Update kernel. Initiate kernel update using mos-kernel update script (admin only) Body: version. Responses: 200, 400, 401, 403, 500.
POST /mos/rollbackkernel. Rollback kernel. Initiate kernel rollback using mos-kernel update rollback script (admin only) Responses: 200, 400, 401, 403, 500.
GET /mos/bootbackupfiles. Get boot backup files. Retrieve array of .tar and .tar.gz backup files from the boot backup destination (admin only). Returns empty array if backup plugin not installed or no backup path configured Responses: 200, 401, 403, 500.
POST /mos/installtodisk. Install MOS to disk. Install MOS to a specified disk with the specified filesystem using mos-install script (admin only) Body: disk, filesystem, extra_partition, tar_file, backup_label. Responses: 200, 400, 401, 403, 500.
GET /mos/dashboard. Get dashboard layout. Retrieve current dashboard card layout configuration (admin only) Responses: 200, 401, 403, 500.
POST /mos/dashboard. Update dashboard layout. Update dashboard card layout configuration (admin only) Body: left, right, visibility, interface. Responses: 200, 400, 401, 403, 500.
GET /mos/readfile. Read a file from the filesystem. Read the content of any file on the filesystem Parameters: path. Responses: 200, 400, 401, 403, 404, 500.
POST /mos/editfile. Edit a file on the filesystem. Edit any file on the filesystem. Creates a backup with .backup extension if create backup is true Body: path, content, create_backup. Responses: 200, 400, 401, 403, 404, 500.
POST /mos/rename. Rename a file or directory. Renames a file or directory by changing only its name within the same parent directory. This is a synchronous operation and returns immediately. Validation: - new name must not contain forbidden characters: \ / : ? " < | or control characters - new name must not have leading/trailing whitespace - new name must not be identical to the current name - Case-only changes (e.g., Movies β movies) are allowed (Linux is case-sensitive) - An error is thrown if a file/directory with new name already exists in the same directory Body: destination, new_name. Responses: 200, 400, 401, 500.
POST /mos/createfile. Create a new file on the filesystem. Create a new file with optional content and ownership/permission settings Body: path, content, user, group, permissions. Responses: 200, 400, 401, 403, 500.
POST /mos/createfolder. Create a new folder on the filesystem. Create a new folder with optional ownership/permission settings Body: path, user, group, permissions. Responses: 200, 400, 401, 403, 500.
POST /mos/delete. Delete a file or folder from the filesystem. Delete a file or folder with optional force and recursive flags. - For files: deletes the file directly - For empty folders: deletes without recursive flag - For non-empty folders: requires recursive=true Body: path, force, recursive. Responses: 200, 400, 401, 403, 404, 500.
POST /mos/chown. Change ownership of a file or folder. Change the user and group ownership of a file or folder, optionally recursive Body: path, user, group, recursive. Responses: 200, 400, 401, 403, 404, 500.
POST /mos/chmod. Change permissions of a file or folder. Change the permissions of a file or folder, optionally recursive Body: path, permissions, recursive. Responses: 200, 400, 401, 403, 404, 500.
GET /mos/dashboard/interface. Get dashboard network interface setting. Retrieve which network interface is monitored on the dashboard. Returns 'eth0' by default if not configured. Responses: 200, 500.
POST /mos/dashboard/interface. Update dashboard network interface setting. Set which network interface is monitored on the dashboard (system load websocket and /system/load endpoint). Valid interface names include eth0, eth1, br0, bond0, eth0.100 (VLAN), etc. If set to empty or invalid, defaults back to eth0. Body: interface. Responses: 200, 400, 500.
GET /mos/fsnavigator. Browse filesystem with directory/file picker. Navigate directories and files with optional virtual root. - Without roots parameter: Full filesystem access (real / with all directories) - With roots parameter: Virtual root showing only specified directories Parameters: path, type, roots, includeHidden. Responses: 200, 400, 401, 403, 404, 500.
POST /mos/fsnavigator/calc. Calculate directory size. Recursively calculates the total size of a directory and returns it in human-readable format based on user byte format preference (admin only) Body: path. Responses: 200, 400, 401, 403, 404, 500.
GET /mos/fsnavigator/bookmarks. List all filesystem bookmarks. Returns all saved filesystem bookmarks Responses: 200, 401, 500.
POST /mos/fsnavigator/bookmarks. Replace all filesystem bookmarks. Overwrites the entire bookmarks list with the provided array Responses: 200, 400, 401, 500.
PUT /mos/fsnavigator/bookmarks. Create a new filesystem bookmark. Add a new bookmark with a display name and path. Returns 409 if a bookmark with the same name or path already exists. Body: name, path. Responses: 201, 400, 401, 409, 500.
DELETE /mos/fsnavigator/bookmarks. Delete one or all filesystem bookmarks. With body: Delete a single bookmark identified by its path. Without body: Delete all bookmarks. Body: path. Responses: 200, 401, 404, 500.
GET /mos/download. Download a file from the filesystem. Downloads a file as a binary stream. Supports any file type and size. The file is streamed directly without loading it entirely into memory. Use the filesystem navigator (GET /mos/fsnavigator) to browse available files. Parameters: path. Responses: 200, 400, 401, 404, 500.
POST /mos/upload. Upload a file to the filesystem. Uploads a single file to the specified target directory. The file is sent as multipart/form-data. Use the filesystem navigator (GET /mos/fsnavigator) to browse available directories. Body: file, path. Responses: 200, 400, 404, 500.
GET /mos/fileoperations. List all file operations. Returns all running and recently completed file operations (completed operations are retained for 5 minutes). Sorted by status (running first) then by start time. Responses: 200, 401, 500.
POST /mos/fileoperations. Start a file copy or move operation. Starts a background file copy or move operation with progress tracking. The operation runs asynchronously - use the WebSocket namespace /fileoperations or poll GET /mos/fileoperations for progress updates. MergerFS Protection: Copy operations within the same MergerFS pool are blocked to prevent data corruption. This includes paths under /mnt/POOLNAME and /var/mergerfs/POOLNAME/. Move operations are always allowed. Same-Filesystem Moves: If source and destination are on the same filesystem, the move is instant (rename). The response will have instantMove: true in this case. Disk Space Check: Before starting the transfer, available disk space at the destination is checked. The operation will fail if insufficient space is detected. Body: operation, source, destination, onConflict. Responses: 200, 400, 401, 500.
DELETE /mos/fileoperations/{id}. Cancel a running file operation. Cancels a running copy or move operation by sending SIGINT to the rsync process. Partially transferred files may remain at the destination. Parameters: id. Responses: 200, 400, 401, 404, 500.
GET /mos/runningfsoperations. Get count of running file operations. Returns the number of currently running (preparing + running) file operations as an integer. Responses: 200, 401, 500.
GET /mos/sensors. Get mapped sensor values. Returns sensor values grouped by type (fan, temperature, power, voltage, psu, other) Responses: 200, 401, 500.
POST /mos/sensors. Create sensor mapping(s). Create one or multiple sensor mappings. Request body must be an array of sensor objects. Responses: 201, 207, 400, 401, 500.
PUT /mos/sensors. Replace all sensor mappings. Replace the entire sensor configuration. Useful for bulk reordering or replacing all sensors at once. Existing sensors not in the new config will be deleted. Body: fan, temperature, power, voltage, psu, other. Responses: 200, 400, 401, 500.
GET /mos/sensors/unmapped. Get unmapped sensors. Returns sensor data in the same structure as /system/sensors, but with already mapped sources removed. Empty adapters (with no remaining sensors) are also removed. Responses: 200, 401, 500.
GET /mos/sensors/config. Get sensor mapping configuration. Returns full configuration for all sensor mappings grouped by type Responses: 200, 401, 500.
GET /mos/sensors/view. Get sensors view settings. Returns UI visibility settings for sensor columns Responses: 200, 401, 500.
POST /mos/sensors/view. Update sensors view settings. Update UI visibility settings for sensor columns Body: index, name, type, subtype, manufacturer, model, value, unit, actions. Responses: 200, 400, 401, 500.
PATCH /mos/sensors/{id}. Update an existing sensor mapping. Partially update fields of an existing sensor mapping. Changing type will move sensor to new group. Parameters: id. Body: name, manufacturer, model, subtype, type, source, unit, multiplier, divisor, value_range, transform, enabled, index. Responses: 200, 400, 401, 404, 500.
DELETE /mos/sensors/{id}. Delete a sensor mapping. Delete a sensor mapping and reindex remaining sensors Parameters: id. Responses: 200, 401, 404, 500.
GET /mos/tokens. Get all tokens. Retrieve all tokens (github, dockerhub, etc.) decrypted from /boot/config/system/tokens.json (admin only) Responses: 200, 401, 403, 500.
POST /mos/tokens. Update tokens (partial updates supported). Update one or more tokens (encrypted with JWT SECRET) in /boot/config/system/tokens.json. Only provided tokens will be updated. (admin only) Body: github, dockerhub. Responses: 200, 400, 401, 403, 500.
GET /mos/validatetokens. Validate configured tokens. Validates GitHub and DockerHub tokens and returns their status. - GitHub: Returns rate limit info (limit, remaining, reset, used, resource) - DockerHub: Returns validation status and rate limit info if available If both tokens are empty, returns an error. Responses: 200, 401, 403, 500.
GET /mos/zram. Get ZRAM configuration and status. Retrieve current ZRAM configuration including module status (admin only) Responses: 200, 401, 403, 500.
POST /mos/zram. Update ZRAM configuration. Update ZRAM settings. Changing enabled from false to true loads the module and activates devices. Changing from true to false checks for mounted ramdisks and unloads the module (admin only) Body: enabled, zram_devices, devices. Responses: 200, 400, 401, 403, 500.
GET /mos/zram/algorithms. Get available compression algorithms. Returns list of compression algorithms supported by the kernel for ZRAM Responses: 200, 401, 500.
GET /mos/zram/status. Get ZRAM device status. Get detailed status of all ZRAM devices including compression stats (admin only) Responses: 200, 401, 403, 500.
POST /mos/zram/devices. Add a new ZRAM device. Add a new ZRAM device configuration. For swap type, config.priority is required. For ramdisk type, config.filesystem is required and config.uuid will be auto-generated if not provided (admin only) Body: name, enabled, algorithm, size, type, config. Responses: 200, 400, 401, 403, 500.
POST /mos/zram/devices/{id}. Update a ZRAM device. Update an existing ZRAM device configuration. Disabling a device will reset it (swap will be disabled, ramdisk must not be mounted) (admin only) Parameters: id. Responses: 200, 400, 401, 403, 404, 500.
DELETE /mos/zram/devices/{id}. Delete a ZRAM device. Delete a ZRAM device configuration. Device will be deactivated first (admin only) Parameters: id. Responses: 200, 400, 401, 403, 404, 500.
GET /mos/zswap/algorithms. Get available zswap compression algorithms. Returns list of compression algorithms supported by the kernel for zswap Responses: 200, 401, 500.
GET /mos/zswap/status. Get swap and zswap status. Returns current swap status including active swaps, zswap configuration, and any pending operations Responses: 200, 401, 500.
GET /mos/diag. Download diagnostics tar.gz bundle. Collects system config files, command outputs, and API service data into a tar.gz archive. The archive contains raw config files, processed API responses, system info, and network details. If individual collectors fail, their errors are logged in errors.txt. Responses: 200, 500.
File Operations WebSocket. File Operations WebSocket
GET /mos/fileoperations/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time file operation monitoring. Connection: Connect to WebSocket at /api/v1/fileoperations namespace Events to emit (client β server): - subscribe-operation - Subscribe to a specific operation by ID - subscribe-all - Subscribe to all file operations - unsubscribe-operation - Unsubscribe from a specific operation - unsubscribe-all - Unsubscribe from all file operations - update-preferences - Update byte format preference Events to listen for (server β client): - fileoperations-update - Progress update for a single operation - fileoperations-list - All operations (sent on subscribe-all) - fileoperations-subscription-confirmed - Subscription confirmed - fileoperations-unsubscription-confirmed - Unsubscription confirmed - preferences-updated - Preferences updated confirmation - error - Error occurred Update Interval: Progress updates are broadcast every 2 seconds. State changes (completed, failed, cancelled) are sent immediately. Important: Operations continue running in the background even when no WebSocket clients are connected. The WebSocket is only for monitoring. Operations are started and cancelled via REST endpoints. Example Usage: Connect to WebSocket: const socket = io('http://localhost:998/api/v1/fileoperations', { path: '/api/v1/socket.io/' }); Subscribe to a specific operation: socket.emit('subscribe-operation', { token: 'your-jwt-token', operationId: '1742742123456' }); Subscribe to all operations: socket.emit('subscribe-all', { token: 'your-jwt-token' }); Listen for updates: // Single operation update (progress, status changes) socket.on('fileoperations-update', (data) = { console.log([${data.id}] ${data.operation} ${data.status}); console.log( Progress: ${data.progress}%); console.log( Speed: ${data.speed human}); console.log( ETA: ${data.eta}); console.log( ${data.bytesTransferred human} / ${data.bytesTotal human}); if (data.instantMove) { console.log(' Instant move (same filesystem)'); } if (data.status === 'completed') { console.log(' Completed at:', data.completedAt); } if (data.status === 'failed') { console.error(' Error:', data.error); } }); // All operations list (sent on subscribe-all) socket.on('fileoperations-list', (operations) = { console.log(${operations.length} operations); operations.forEach(op = { console.log( ${op.id}: ${op.operation} ${op.status} ${op.progress}%); }); }); Update byte format preference: socket.emit('update-preferences', { byte format: 'decimal' }); Unsubscribe: socket.emit('unsubscribe-operation', { operationId: '1742742123456' }); socket.emit('unsubscribe-all'); Responses: 200.
MOS Hub. MOS Hub Repository Management
GET /mos/hub/settings. Get hub settings. Retrieves hub configuration (enabled, initial update, schedule, update check) Responses: 200, 500.
POST /mos/hub/settings. Update hub settings. Updates hub configuration (enabled, initial update, schedule, update check) Body: enabled, initial_update, schedule, page_entries, update_check. Responses: 200, 400, 500.
GET /mos/hub/repositories. Get all repository URLs. Retrieves list of configured repository URLs Responses: 200, 500.
POST /mos/hub/repositories. Set repository URLs. Replaces all repository URLs with the provided list Responses: 200, 400, 500.
GET /mos/hub/knownrepositories. Get known repository URLs. Returns the cached list of known repository URLs (empty array if none). Responses: 200, 500.
POST /mos/hub/update. Update repositories. Refreshes the known repositories list and downloads all configured and known repositories via git clone Responses: 200, 400, 500.
GET /mos/hub/index. Get template index. Returns all templates from all repositories with maintainer info Parameters: search, category, type, sort, order, limit, skip, arch_filter. Responses: 200, 400, 500.
GET /mos/hub/types. Get available template types. Returns available template types (docker, compose, lxc, plugin, vm) that exist in repositories Responses: 200, 500.
GET /mos/hub/categories. Get available template categories. Returns available categories (AI, Backup, Media, etc.). Use ?all=true to return all allowed categories, not only those in use. Parameters: all. Responses: 200, 500.
POST /mos/hub/docker/template. Get docker template content. Returns the raw content of a docker template JSON Body: template. Responses: 200, 400, 404, 500.
POST /mos/hub/compose/template. Get compose files content. Returns name, yaml, env, icon and web ui url from compose template Body: template, yaml, env. Responses: 200, 400, 404, 500.
POST /mos/hub/plugin/template. Get plugin template content. Returns the raw content of a plugin template JSON Body: template. Responses: 200, 400, 404, 500.
MOS Plugins. MOS Plugin Management
GET /mos/plugins. List all installed plugins. Returns a list of all installed plugins with their manifest data Responses: 200, 500.
POST /mos/plugins/query. Query a plugin command. Executes a command from /usr/bin/plugins and returns output. Symlinks are allowed but their targets are validated. Dangerous commands like rm, mkdir, bash, sh, etc. are blocked both by name and as symlink targets. Body: command, args, timeout, parse_json. Responses: 200, 400, 500.
POST /mos/plugins/releases. Get GitHub releases for a plugin repository. Fetches and caches up to 50 releases from a GitHub repository Body: repository, refresh. Responses: 200, 400, 404, 500.
POST /mos/plugins/install. Install a plugin from Hub template. Downloads and installs a plugin using a Hub template path and release tag Body: template, tag. Responses: 200, 400, 500.
GET /mos/plugins/settings/{pluginName}. Get plugin settings. Retrieves settings.json for a specific plugin Parameters: pluginName. Responses: 200, 400, 404, 500.
POST /mos/plugins/settings/{pluginName}. Update plugin settings. Writes settings.json for a specific plugin Parameters: pluginName. Responses: 200, 400, 404, 500.
POST /mos/plugins/updatecheck. Check for plugin updates. Compares installed plugin versions with latest available on GitHub Body: notify. Responses: 200, 500.
POST /mos/plugins/update. Update plugins. Updates one or all plugins with available updates Body: plugin. Responses: 200, 400, 500.
DELETE /mos/plugins/delete/{pluginName}. Delete a plugin. Removes a plugin including dpkg package and all related files Parameters: pluginName. Responses: 200, 400, 500.
POST /mos/plugins/executefunction. Execute a function from a plugin. Executes a specified function from the plugin's functions file. Some functions are blocked for security. Body: plugin, function, name, restart. Responses: 200, 400, 500.
GET /mos/plugins/driver/{pluginName}. Get driver package info for a driver plugin. Returns the installed driver package path and name for the current kernel. Only works for driver plugins. Parameters: pluginName. Responses: 200, 400, 500.
Terminal. Terminal Management
GET /terminal/sessions. List all terminal sessions. Shows all active terminal sessions with details (admin only) Useful for monitoring and session management. Responses: 200, 401, 403.
POST /terminal/create. Create new terminal session. Creates a new terminal session with flexible options (admin only) Usage Examples: Root Shell (with Pixel Dimensions - recommended): { "shell": "/bin/bash", "cwd": "/", "width": 1024, "height": 768 } Root Shell (with Cols/Rows - legacy): { "shell": "/bin/bash", "cwd": "/", "cols": 120, "rows": 40 } Docker Container: { "command": "docker", "args": ["exec", "-it", "nginx", "/bin/sh"] } LXC Container: { "command": "lxc-attach", "args": ["-n", "ubuntu", "--", "/bin/bash"] } Log Viewing (Read-Only): { "command": "tail", "args": ["-f", "-n", "200", "/var/log/syslog"], "readOnly": true } Docker Logs: { "command": "docker", "args": ["logs", "-f", "--tail", "100", "nginx"], "readOnly": true } System Monitoring: { "command": "htop" } After creation, connect via WebSocket using the session ID. Body: command, args, shell, width, height, cols, rows, cwd, readOnly. Responses: 201, 400, 401, 403, 500.
GET /terminal/{sessionId}. Terminal session info. Shows information about a specific terminal session (admin only) Parameters: sessionId. Responses: 200, 401, 403, 404.
DELETE /terminal/{sessionId}. Terminate terminal session. Terminates a terminal session (admin only) Parameters: sessionId. Responses: 200, 401, 403, 404.
POST /terminal/{sessionId}/resize. Resize terminal. Changes the terminal size for a session (admin only) Supports two modes: - Pixel-based (recommended) : width and height in pixels - Legacy : cols and rows in characters/lines Parameters: sessionId. Body: width, height, cols, rows. Responses: 200, 400, 401, 403, 404.
Terminal WebSocket. Terminal WebSocket management and documentation
GET /api/v1/terminal/websocket/events. Terminal WebSocket Events Documentation. Get comprehensive documentation for Terminal WebSocket events and usage. Connection Connect to the Terminal WebSocket namespace: const socket = io('http://localhost:3000/api/v1/terminal', { path: '/socket.io/', auth: { token: 'your-jwt-token' } }); Authentication All terminal operations require admin-level authentication. Include your JWT token in event data. Basic Usage 1. Create a new terminal session: socket.emit('create-session', { token: 'your-jwt-token', options: { cols: 80, rows: 24, cwd: '/home/user' } }); 2. Join an existing session: socket.emit('join-session', { sessionId: 'terminal 1694123456789 abc123def', token: 'your-jwt-token' }); 3. Send input to terminal: socket.emit('terminal-input', 'ls -la\n'); 4. Listen for output: socket.on('terminal-output', (data) = { console.log(data); }); 5. Resize terminal: socket.emit('terminal-resize', { cols: 120, rows: 30 }); Session Management List all sessions: socket.emit('list-sessions', { token: 'your-jwt-token' }); socket.on('sessions-list', (sessions) = { console.log(sessions); }); Kill a session: socket.emit('kill-session', { sessionId: 'terminal 1694123456789 abc123def', token: 'your-jwt-token' }); Get statistics: socket.emit('get-stats', { token: 'your-jwt-token' }); socket.on('terminal-stats', (stats) = { console.log(stats); }); Error Handling Always listen for error events: socket.on('error', (error) = { console.error('Terminal error:', error.message); }); Responses: 200, 401.
GET /api/v1/terminal/websocket/stats. Get Terminal WebSocket Statistics. Get real-time statistics about terminal WebSocket connections and sessions. This endpoint provides information about: - Total number of terminal sessions - Number of active sessions with WebSocket connections - Number of connected WebSocket clients - Detailed information about each session Responses: 200, 401, 500.
NUT. Network UPS Tools configuration and status
GET /nut/settings. Get NUT settings. Returns the full NUT configuration model, filled with defaults for missing fields (admin only). Responses: 200, 401, 403, 500.
POST /nut/settings. Update NUT settings. Deep-merges the given fields into the model and restarts the NUT services only when an essential (non stop services) setting changed. Numeric fields accept numbers or strings (comma decimals allowed). The enabled flag is managed via the network services endpoint and is ignored here. Body: mode, spindown_disks, server, monitor, shutdown, timers, stop_services. Responses: 200, 400, 401, 403, 500.
GET /nut/status. Get UPS status. Returns live UPS status via upsc. reachable=false when NUT is disabled or upsd cannot be queried. Responses: 200, 401, 403, 500.
GET /nut/scripts/{event}. Get the script for a NUT event. Reads the event script from /boot/config/system/nut/{event}.sh (admin only). Parameters: event. Responses: 200, 400, 401, 403, 404, 500.
POST /nut/scripts/{event}. Update the script for a NUT event. Writes the event script to /boot/config/system/nut/{event}.sh, creating the directory and the file if they do not exist yet. NUT is not restarted: upsmon runs the script straight from the boot stick when the event fires, so changes take effect immediately. Parameters: event. Body: content, create_backup. Responses: 200, 400, 401, 403, 500.
NUT WebSocket. Real-time UPS status monitoring via WebSocket
GET /nut/websocket/events. WebSocket Events Documentation. This endpoint documents the WebSocket events for real-time NUT/UPS status monitoring. Connection: Connect to WebSocket at /api/v1/nut namespace Authorization: Admin only. Non-admin users are rejected; admin API tokens additionally need read permission for the nut resource. Events to emit (client β server): - subscribe-nut-status: Subscribe to UPS status updates - unsubscribe-nut-status: Unsubscribe from UPS status updates - get-nut-status: Get immediate UPS status (one-time) Events to listen for (server β client): - nut-status-update: Real-time UPS status (every 5s) - nut-status-subscription-confirmed: Subscription confirmation - nut-status-unsubscription-confirmed: Unsubscription confirmation - error: General error messages Example Usage: Connect to WebSocket: const socket = io('http://localhost:3000/api/v1/nut', { path: '/api/v1/socket.io/' }); Subscribe to UPS status: socket.emit('subscribe-nut-status', { token: 'your-jwt-token' }); Listen for updates: socket.on('nut-status-update', (data) = { console.log('UPS status:', data.status, data.data); }); Responses: 200.
GET /nut/websocket/stats. Get NUT WebSocket statistics. Returns current statistics for the NUT status WebSocket Responses: 200, 503.
Notifications. Notifications Management
GET /notifications. Get all notifications. Retrieve all system notifications with optional filtering by read status, limit, and sort order - admin only Parameters: read, limit, order. Responses: 200, 401, 403, 500.
DELETE /notifications. Delete all notifications. Delete all system notifications - admin only Responses: 200, 401, 403, 500.
DELETE /notifications/{id}. Delete notification by ID. Delete a specific notification using its ID - admin only Parameters: id. Responses: 200, 401, 403, 404, 500.
GET /notifications/stats. Get notification statistics. Get statistics about notifications including read/unread counts and priority breakdown - admin only Responses: 200, 401, 403, 500.
PUT /notifications/{id}/read. Mark notification as read. Mark a specific notification as read using its ID - admin only Parameters: id. Responses: 200, 401, 403, 404, 500.
PUT /notifications/read/multiple. Mark multiple notifications as read. Mark multiple notifications as read using their IDs - admin only Responses: 200, 400, 401, 403, 404, 500.
PUT /notifications/read/all. Mark all notifications as read. Mark all notifications as read - admin only Responses: 200, 401, 403, 500.
GET /notifications/push/vapid-key. Get VAPID public key. Returns the VAPID public key needed by the frontend to create a push subscription - admin only Responses: 200, 401, 403, 500.
POST /notifications/push/subscribe. Subscribe to push notifications. Register a browser push subscription for the authenticated user. The subscription object is provided by the browser Push API - admin only Body: endpoint, keys. Responses: 201, 400, 401, 403, 500.
DELETE /notifications/push/subscribe. Unsubscribe from push notifications. Remove a browser push subscription. The endpoint URL identifies the subscription to remove - admin only Body: endpoint. Responses: 200, 400, 401, 403, 404, 500.
LLM. LLM Integration and Chat
GET /llm/status. Get LLM container status. Returns the current status of the LLM interconnect container Responses: 200, 401.
POST /llm/chat. Send a message to the LLM. Sends a chat message to the LLM via the interconnect container Body: message, context. Responses: 200, 401, 503.
Parts of this documentation were created with the assistance of AI tools. All AI-generated content has undergone review, but it may still contain inaccuracies, omissions, or outdated information.