03 Device API

This guide describes how to query the built-in UGS API, and the typical responses of the NAS.

📝 Authentication - How to get your token

❗ Important: Add &token={token} to every URL below. Every API call must include a valid token! ❗

To obtain a valid token from your NAS:

• Open the NAS Web UI in your browser and log in.
• Press F12 to open Developer Tools.
• Use Ctrl + F to search for static_token or api_token.
  
• Double-click the token, copy / paste it sowewhere (e.g. an editor).

Update: Since firmware 1.3 (06/2025), static_token no longer works. Always use api_token.

📝 Valid Endpoints and how to query them

Call these endpoints to get full system information:

📌 System Information

By using a get request:

GET /ugreen/v1/sysinfo/machine/common?token=your_token

Or alternatively in your browser:

http://192.168.178.9:9999/ugreen/v1/sysinfo/machine/common?token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "common": {
      "nas_name": "DXP480TPLUS",
      "model": "DXP480T Plus",
      "serial": "********",
      "mac": ["**:**:**:**:**:**"],
      "system_version": "1.6.0",
      "run_time": 24386
    },
    "hardware": {
      "cpu": [{"model": "Intel i5", "core": 10, "thread": 12}],
      "mem": [{"manufacturer": "Samsung", "size": 8}],
      "net": [{"model": "eth0", "ip": "192.168.x.x"}]
    }
  }
}

📌 System Status

GET /ugreen/v1/desktop/components/data?id=desktop.component.SystemStatus&token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "dev_name": "DXP480TPLUS",
    "network_info": [
      {"connection": 1, "ipv4": "192.168.x.x", "label": "LAN1"}
    ],
    "system_version": "1.6.0",
    "total_run_time": 24411
  }
}

📌 Device Monitoring

GET /ugreen/v1/desktop/components/data?id=desktop.component.DeviceMonitoring&token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "cpu_usage_rate": 0.8,
    "ram_usage_rate": "28.8",
    "upload_speed": {"value": 3.8, "unit": "MB/s"},
    "download_speed": {"value": 6.6, "unit": "MB/s"}
  }
}

📌 Temperature Monitoring

GET /ugreen/v1/desktop/components/data?id=desktop.component.TemperatureMonitoring&token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "cpu_temperature": 41,
    "disk_list": [
      {"label": "M.2 Drive 1", "temperature": 43}
    ],
    "fan_list": [
      {"speed": 685},
      {"speed": 799}
    ],
    "message": "Temperature normal"
  }
}

📌 Storage Pools

GET /ugreen/v1/storage/pool/list?token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "result": [
      {
        "name": "pool1",
        "total": 983681728512,
        "used": 983547510784,
        "free": 134217728,
        "disks": [
          {"label": "M.2 Drive 1", "size": 983684874240}
        ],
        "volumes": [
          {"label": "Volume 1", "filesystem": "btrfs"}
        ]
      }
    ]
  }
}

📌 Disks

GET /ugreen/v2/storage/disk/list?token=your_token

Example response (shortened):

{
  "code": 200,
  "data": {
    "result": [
      {
        "model": "Samsung SSD 1TB",
        "size": 1000204886016,
        "label": "M.2 Drive 1",
        "status": 1,
        "temperature": 42
      }
    ]
  }
}

📝 Important Notes

• All API requests require token=your_token at the end.
• The token is valid for a limited time - generate a new one if needed.
• Keep sensitive data like serial numbers and MAC addresses private.

🗣️ Share your responses!

If you come across different API endpoints, please post them here: 👉 GitHub Discussion #43
This helps with the development and imrpvement of this integration.