api-reference

Unraid API - Complete Reference Guide

> **⚠️ DEVELOPER REFERENCE ONLY** — This file documents the raw GraphQL API schema for development and maintenance purposes (adding new queries/mutations). Do NOT use these curl/GraphQL examples for MCP tool usage. Use `unraid(action=..., subaction=...)` calls instead. See [`SKILL.md`](../SKILL.md) for the correct calling convention.

**Tested on:** Unraid 7.2 x86_64 **Date:** 2026-01-21 **API Type:** GraphQL **Base URL:** `https://YOUR-UNRAID-SERVER/graphql`

This reference documents raw GraphQL schema behavior. The MCP tool exposes safe read subactions for direct roots separately: `system/display_details`, `system/network_access_urls`, `system/server_details`, `connect/status`, and `customization/details`; those omit `server.apikey`, `connect.settings.values`, and raw activation-code values by default.

---

📊 Summary

Out of 46 total GraphQL query endpoints:

• **✅ 27 fully working read-only endpoints**
• **⚠️ 1 works but returns empty** (`plugins`)
• **❌ 3 return null** (`flash`, `parityHistory`, `services`)
• **❓ 15 untested** (mostly write/mutation operations)

---

Authentication

All requests require the `x-api-key` header:

-H "x-api-key: YOUR_API_KEY_HERE"

How to Generate API Key:

1. Log in to Unraid WebGUI 2. Settings → Management Access → API Keys 3. Create API Key with **Viewer** role (read-only) 4. Copy the generated key

---

🎯 All 27 Working Read-Only Endpoints

1. System Info & Metrics

**info** - Hardware Specifications

Get CPU, OS, motherboard, and hardware details.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "{ info { time cpu { model cores threads } os { platform distro release arch } system { manufacturer model version uuid } } }"
  }' | jq '.'

**Response:**

{
  "data": {
    "info": {
      "time": "2026-01-21T12:57:22.539Z",
      "cpu": {
        "model": "183",
        "cores": 16,
        "threads": 24
      },
      "os": {
        "platform": "linux",
        "distro": "Unraid OS",
        "release": "7.2 x86_64",
        "arch": "x64"
      },
      "system": {
        "manufacturer": "Micro-Star International Co., Ltd.",
        "model": "MS-7E07",
        "version": "1.0",
        "uuid": "fec05753-077c-8e18-a089-047c1644678a"
      }
    }
  }
}

---

**metrics** - Real-Time Usage Stats

Get current CPU and memory usage percentages.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "{ metrics { cpu { percentTotal } memory { total used free percentTotal swapTotal swapUsed swapFree } } }"
  }' | jq '.'

**Response:**

{
  "data": {
    "metrics": {
      "cpu": {
        "percentTotal": 20.99
      },
      "memory": {
        "total": 134773903360,
        "used": 129472622592,
        "free": 5301280768,
        "percentTotal": 59.97,
        "swapTotal": 0,
        "swapUsed": 0,
        "swapFree": 0
      }
    }
  }
}

**Note:** Memory values are in bytes.

---

**online** - Server Online Status

Simple boolean check if server is online.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "{ online }" }' | jq '.'

**Response:**

{
  "data": {
    "online": true
  }
}

---

**isInitialSetup** - Initial Setup Status

Check if server has completed initial setup.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "{ isInitialSetup }" }' | jq '.'

**Response:**

{
  "data": {
    "isInitialSetup": false
  }
}

---

2. Storage & Disks

**array** - Array Status & Disks

Get array state, disk details, temperatures, and capacity.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "{ array { state disks { id name device size status temp fsSize fsFree fsUsed fsType rotational isSpinning } parityCheckStatus { status progress errors speed } } }"
  }' | jq '.'

**Response (sample):**

{
  "data": {
    "array": {
      "state": "STARTED",
      "disks": [
        {
          "id": "3cb1026338736ed07b8afec2c484e429710b0f6550dc65d0c5c410ea9d0fa6b2:WDC_WD120EDBZ-11B1HA0_5QGWN5DF",
          "name": "disk1",
          "device": "sdb",
          "size": 11718885324,
          "status": "DISK_OK",
          "temp": 38,
          "fsSize": 11998001574,
          "fsFree": 1692508541,
          "fsUsed": 10305493033,
          "fsType": "xfs",
          "rotational": true,
          "isSpinning": true
        }
      ],
      "parityCheckStatus": {
        "status": "NEVER_RUN",
        "progress": 0,
        "errors": null,
        "speed": "0"
      }
    }
  }
}

**Note:** Sizes are in kilobytes. Temperature in Celsius.

---

**disks** - All Physical Disks

Get ALL disks including array disks, cache SSDs, and boot USB.

curl -s -X POST "https://YOUR-UNRAID/graphql" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "{ disks { id name } }"
  }' | jq '.'

**Response (sample):**

{
  "data": {
    "disks": [
      {
        "id": "3cb1026338736ed07b8afec2c484e429710b0f6550dc65d0c5c410ea9d0fa6b2:04009732070823130633",
        "name": "Cruzer Glide"
      },
      {
        "id": "3cb1026338736ed07b8afec2c484e429710b0f6550dc65d0c5c410ea9d0fa6b2:5QGWN5DF",
        "name": "WDC WD120EDBZ-11B1HA0"
      },
      {
        "id": "3cb1026338736ed07b8afec2c484e429710b0f6550dc65d0c5c410ea9d0fa6b2:S6S2NS0TB18572X",
        "name": "Samsung SSD 970 EVO Plus 2TB"
      }
    ]
  }
}

**Returns:** Array disks + Cache SSDs + Boot USB (17 disk