An async Python client library for the Unraid GraphQL API.

• 🔄 Async/await - Built with aiohttp for non-blocking operations
• 🏠 Home Assistant ready - Accepts external aiohttp.ClientSession for integration
• 🔒 Secure by design - GraphQL variables, no string interpolation
• 📦 Typed - Full type hints with py.typed marker (PEP 561)
• 🧩 Pydantic models - Structured response parsing
• 🔌 SSL auto-discovery - Handles Unraid's "No", "Yes", and "Strict" SSL modes
• ⚡ Redirect handling - Supports myunraid.net remote access

pip install unraid-api

import asyncio
from unraid_api import UnraidClient

async def main():
    async with UnraidClient("192.168.1.100", "your-api-key") as client:
        # Test connection
        if await client.test_connection():
            print("Connected!")

            # Get version info
            version = await client.get_version()
            print(f"Unraid {version['unraid']}, API {version['api']}")

asyncio.run(main())

async with UnraidClient(host, api_key) as client:
    # Custom GraphQL query
    result = await client.query("""
        query {
            info {
                os { hostname uptime }
                cpu { name cores threads }
                memory { total used }
            }
        }
    """)
    print(result["info"]["os"]["hostname"])

async with UnraidClient(host, api_key) as client:
    # Start a container
    await client.start_container("container:plex")

    # Stop a container
    await client.stop_container("container:plex")

async with UnraidClient(host, api_key) as client:
    # Start a VM
    await client.start_vm("vm:windows-11")

    # Stop a VM
    await client.stop_vm("vm:windows-11")

async with UnraidClient(host, api_key) as client:
    # Start/stop array
    await client.start_array()
    await client.stop_array()

    # Parity check
    await client.start_parity_check(correct=True)
    await client.pause_parity_check()
    await client.resume_parity_check()
    await client.cancel_parity_check()

    # Disk spin control
    await client.spin_up_disk("disk:1")
    await client.spin_down_disk("disk:1")

import aiohttp
from unraid_api import UnraidClient

async def setup_client(session: aiohttp.ClientSession):
    """Use shared session from Home Assistant."""
    client = UnraidClient(
        host="192.168.1.100",
        api_key="your-api-key",
        session=session,  # Injected session won't be closed by client
        verify_ssl=False,
    )
    return client

async with UnraidClient(host, api_key) as client:
    # Stream CPU metrics
    async for cpu in client.subscribe_cpu_metrics():
        print(f"CPU: {cpu.percentTotal}%")

    # Stream Docker container stats
    async for stats in client.subscribe_container_stats("container:plex"):
        print(f"CPU: {stats.cpuPercent}%, Mem: {stats.memUsage}")

    # Generic subscription with custom query
    async for data in client.subscribe("subscription { arraySubscription { state } }"):
        print(f"Array state: {data['state']}")

Response data can be parsed into typed models:

from unraid_api.models import DockerContainer, VmDomain, UnraidArray

# Parse container data
container = DockerContainer(**container_data)
print(f"{container.name}: {container.state}")

# Parse array data
array = UnraidArray(**array_data)
print(f"Array: {array.state}, Capacity: {array.capacity.usage_percent}%")

from unraid_api import UnraidClient
from unraid_api.exceptions import (
    UnraidAPIError,
    UnraidAuthenticationError,
    UnraidConnectionError,
    UnraidSSLError,
    UnraidTimeoutError,
)

async with UnraidClient(host, api_key) as client:
    try:
        await client.query("query { online }")
    except UnraidAuthenticationError:
        print("Invalid API key")
    except UnraidSSLError:
        print("SSL certificate verification failed")
    except UnraidConnectionError:
        print("Cannot reach server")
    except UnraidTimeoutError:
        print("Request timed out")
    except UnraidAPIError as e:
        print(f"API error: {e}")

• ServerInfo - Server info for HA device registration
• SystemInfo - System information
• SystemMetrics - CPU, memory, temperature, power, uptime metrics (includes TemperatureMetrics)
• Vars - System configuration variables
• Registration - License/registration info
• Flash - Flash drive information
• Owner - Server owner info

• UnraidArray - Array state and disks
• ArrayDisk - Individual array disk
• ArrayCapacity - Capacity calculations
• PhysicalDisk - Physical disk details (serialNum, firmwareRevision, partitions)
• DiskPartition - Disk partition info (name, fsType, size)
• Share - User share with usage and comment

• DockerContainer - Container with ports, state, mounts, Tailscale, template ports
• DockerNetwork - Docker network configuration
• VmDomain - Virtual machine (id, name, state)
• TailscaleStatus - Tailscale hostname, DNS name, and online status
• ContainerTemplatePort - Template port configuration
• ContainerUpdateStatus - Container update availability
• DockerPortConflicts - Port conflict detection

• Service - System service status
• UPSDevice - UPS with battery/power info
• UPSConfiguration - UPS hardware/software configuration
• Plugin - Installed plugin info
• LogFile - Log file metadata
• LogFileContent - Log file contents
• DisplaySettings - Display and temperature threshold settings
• KeyFile - Registration key file location and contents

• Cloud - Unraid Connect cloud status (deprecated — removed from live API)
• Connect - Connect configuration (deprecated — removed from live API)
• RemoteAccess - Remote access settings (deprecated — removed from live API)

• Notification - System notification (with link, type, formattedTimestamp)
• NotificationOverview - Notification counts
• NotificationOverviewCounts - Per-importance notification counts

• CpuCore - Per-core CPU usage (percentTotal, percentUser, percentSystem, percentIdle, percentNice, percentIrq, percentGuest, percentSteal)
• CpuMetrics - CPU usage with per-core breakdown
• CpuTelemetryMetrics - CPU power and temperature
• MemoryUtilization - Full memory data (total, used, free, available, active, buffcache, swap)
• MemoryMetrics - System memory total/used/free
• ArraySubscriptionUpdate - Array state and capacity updates
• DockerContainerStats - Real-time container resource metrics
• TemperatureMetrics - Temperature sensors with summary and per-sensor data
• TemperatureSensor - Individual sensor with reading, thresholds, and status helpers
• TemperatureReading - Temperature value, unit, and status
• TemperatureSummary - Average, hottest, coolest, warning/critical counts
• SensorType - Enum: CPU_PACKAGE, CPU_CORE, DISK, NVME, CUSTOM
• TemperatureUnit - Enum: CELSIUS, FAHRENHEIT
• TemperatureStatus - Enum: NORMAL, WARNING, CRITICAL, UNKNOWN

Note: UnraidSSLError inherits from UnraidConnectionError, so it can be caught with either exception type for backwards compatibility.

• Python 3.14+
• Unraid 7.2.4+ with latest Unraid API
• API key with appropriate permissions

# Clone repository
git clone https://github.com/ruaan-deysel/unraid-api.git
cd unraid-api

# Install dependencies with uv
uv sync --all-extras

# Run tests
uv run pytest tests/ -v --cov=src/unraid_api

# Lint and type check
uv run ruff check .
uv run ruff format .
uv run mypy src/

MIT License - see LICENSE for details.

Contributions welcome! Please ensure:

1. Tests are written first (TDD)
2. No linting errors (ruff check . && mypy src/)
3. GraphQL variables used (no string interpolation)

• Official Unraid API Repository
• GraphQL API Reference
• PyPI Package