Skip to main content

​
Endpoint

GET /api/system
Returns detailed information about the system that Wings is running on, including Wings version, Docker configuration, container statistics, and hardware specifications.

​
Authentication

This endpoint requires authentication using a Bearer token in the Authorization header. 
Authorization: Bearer <your-token>

​
Query Parameters

​
v
string
API version for the response format. Use "2" to receive the full detailed response. Without this parameter, a simplified legacy response is returned.

​
Response Formats

When using ?v=2, the endpoint returns comprehensive system information:
​
version
string
The current Wings version (e.g., "develop" or "v1.11.0")
​
docker
object
Docker-related information
​
system
object
Host system information

​
Legacy Response (Default)

Without the v query parameter, a simplified response is returned for backward compatibility:
​
architecture
string
System architecture (e.g., "amd64")
​
cpu_count
integer
Number of CPU threads available
​
kernel_version
string
Linux kernel version
​
os
string
Operating system type (e.g., "linux")
​
version
string
Wings version

​
Example Requests

curl -X GET "https://wings.example.com/api/system?v=2" \
  -H "Authorization: Bearer your-token-here"

​
Example Responses

{
  "version": "v1.11.0",
  "docker": {
    "version": "24.0.7",
    "cgroups": {
      "driver": "systemd",
      "version": "2"
    },
    "containers": {
      "total": 15,
      "running": 12,
      "paused": 0,
      "stopped": 3
    },
    "storage": {
      "driver": "overlay2",
      "filesystem": "extfs"
    },
    "runc": {
      "version": "1.1.10-0ubuntu1~22.04.1"
    }
  },
  "system": {
    "architecture": "amd64",
    "cpu_threads": 8,
    "memory_bytes": 16777216000,
    "kernel_version": "5.15.0-91-generic",
    "os": "Ubuntu 22.04.3 LTS",
    "os_type": "linux"
  }
}

​
Error Responses

{
  "error": "Unauthorized"
}

​
Use Cases

​
Health Monitoring

This endpoint is useful for monitoring the health and status of your Wings installation: 
async function checkSystemHealth() {
  const info = await fetch('https://wings.example.com/api/system?v=2', {
    headers: { 'Authorization': 'Bearer token' }
  }).then(r => r.json());
  
  // Check if Wings version is up to date
  console.log('Wings Version:', info.version);
  
  // Monitor Docker container stats
  const containerUsage = info.docker.containers.running / info.docker.containers.total;
  console.log(`Container Usage: ${(containerUsage * 100).toFixed(1)}%`);
  
  // Check available resources
  const memoryGB = info.system.memory_bytes / (1024 ** 3);
  console.log(`Total Memory: ${memoryGB.toFixed(2)} GB`);
}

​
Compatibility Checks

Verify that the system meets requirements before deploying servers: 
def verify_system_requirements(system_info):
    # Check cgroup version for proper container management
    if system_info['docker']['cgroups']['version'] != '2':
        print('Warning: cgroup v2 recommended for optimal performance')
    
    # Verify storage driver
    if system_info['docker']['storage']['driver'] != 'overlay2':
        print('Warning: overlay2 storage driver recommended')
    
    # Check available CPU cores
    if system_info['system']['cpu_threads'] < 4:
        print('Warning: At least 4 CPU threads recommended')

​
Implementation Details

The system information is gathered from multiple sources:
  • Wings Version: Read from system.Version constant in system/const.go
  • Docker Information: Retrieved via Docker API using client.ServerVersion() and client.Info()
  • System Details: Collected using Go’s runtime package and /etc/os-release file
  • Kernel Version: Parsed from Docker’s kernel detection utilities
The endpoint returns live data from the system and Docker daemon. For frequently updated monitoring, consider caching responses appropriately to reduce load.