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.

Build docs developers (and LLMs) love

Get started for freeTalk to us