03 Device API

Device API

This guide describes how to query the API of a device, which endpoints are required, and what the typical responses look like.

---

Authentication

Every API call must include a valid token!

How to get your token

Request a token with:

GET http://{nas_ip}:4115/token?username={username}&password={password}

Example response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "YOUR_TOKEN"
  }
}

✅ Important: Add &token={token} to every URL!

---

Required Endpoints

Call these endpoints to get full system information:

---

1. System Information

GET /ugreen/v1/sysinfo/machine/common?token={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"}]
    }
  }
}

---

2. System Status Component

GET /ugreen/v1/desktop/components/data?id=desktop.component.SystemStatus&token={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
  }
}

---

3. Device Monitoring

GET /ugreen/v1/desktop/components/data?id=desktop.component.DeviceMonitoring&token={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"}
  }
}

---

4. Temperature Monitoring

GET /ugreen/v1/desktop/components/data?id=desktop.component.TemperatureMonitoring&token={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"
  }
}

---

5. Storage Pools

GET /ugreen/v1/storage/pool/list?token={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"}
        ]
      }
    ]
  }
}

---

6. Disk List

GET /ugreen/v2/storage/disk/list?token={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 the token as a parameter.
• ⏳ 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 have responses that are not yet shared, please post them here:
👉 GitHub Discussion #43

This helps with development and integration.