unraid-api 1.8.0

Python client library for Unraid's official GraphQL API

unraid-api

An async Python client library for the Unraid GraphQL API.

Features

• 🔄 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

Installation

pip install unraid-api

Quick Start

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())

Usage Examples

Basic Queries

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"])

Docker Container Control

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")

VM Management

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")

Array Operations

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")

Session Injection (Home Assistant)

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

Real-Time Subscriptions (WebSocket)

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']}")

Pydantic Models

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}%")

Exception Handling

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}")

API Reference

UnraidClient

Core Methods

Method	Description
test_connection()	Test if server is reachable
get_version()	Get Unraid and API version
get_server_info()	Get server info for device registration
query(query, variables)	Execute GraphQL query
mutate(mutation, variables)	Execute GraphQL mutation

High-Level Typed Methods (Pydantic Models)

Method	Returns	Description
get_system_metrics()	SystemMetrics	CPU, memory, temperature, power, uptime
typed_get_array()	UnraidArray	Array state, capacity, disks
typed_get_containers()	list[DockerContainer]	All Docker containers
typed_get_vms()	list[VmDomain]	All virtual machines
typed_get_ups_devices()	list[UPSDevice]	UPS devices with battery info
typed_get_shares()	list[Share]	User shares with usage
get_notification_overview()	NotificationOverview	Notification counts
typed_get_vars()	Vars	System configuration variables
typed_get_registration()	Registration	License information
typed_get_services()	list[Service]	System services status
typed_get_flash()	Flash	Flash drive info
typed_get_owner()	Owner	Owner information
typed_get_plugins()	list[Plugin]	Installed API plugins
typed_get_docker_networks()	list[DockerNetwork]	Docker networks
typed_get_log_files()	list[LogFile]	Available log files
typed_get_cloud()	Cloud	⚠️ Deprecated — Cloud status
typed_get_connect()	Connect	⚠️ Deprecated — Connect configuration
typed_get_remote_access()	RemoteAccess	⚠️ Deprecated — Remote access settings
get_container_update_statuses()	list[ContainerUpdateStatus]	Docker container update availability
get_ups_configuration()	UPSConfiguration	UPS hardware/software configuration
get_display_settings()	DisplaySettings	Display and temperature settings
get_docker_port_conflicts()	DockerPortConflicts	Docker LAN port conflicts
get_temperature_metrics()	TemperatureMetrics	Temperature sensors, thresholds, summary

Raw Data Methods

Method	Returns	Description
get_array_status()	dict	Array state and capacity
get_disks()	list[dict]	Physical disks
get_shares()	list[dict]	User shares
get_containers()	list[dict]	Docker containers
get_vms()	list[dict]	Virtual machines
get_ups_status()	list[dict]	UPS devices
get_notifications()	list[dict]	Notifications
get_parity_history()	list[dict]	Parity check history
get_services()	list[dict]	System services
get_plugins()	list[dict]	Installed plugins
get_docker_networks()	list[dict]	Docker networks
get_log_files()	list[dict]	Log files
get_log_file(path)	dict	Log file contents

Control Methods

Method	Description
start_container(id)	Start Docker container
stop_container(id)	Stop Docker container
restart_container(id)	Restart Docker container
start_vm(id)	Start VM
stop_vm(id)	Stop VM (graceful)
force_stop_vm(id)	Force stop VM
pause_vm(id)	Pause VM
resume_vm(id)	Resume paused VM
start_array()	Start disk array
stop_array()	Stop disk array
start_parity_check(correct)	Start parity check
pause_parity_check()	Pause parity check
resume_parity_check()	Resume parity check
cancel_parity_check()	Cancel parity check
spin_up_disk(id)	Spin up disk
spin_down_disk(id)	Spin down disk

Subscription Methods (WebSocket)

Method	Yields	Description
subscribe(subscription, variables)	dict	Generic GraphQL subscription (async generator)
subscribe_container_stats(container_id)	DockerContainerStats	Real-time Docker container resource metrics
subscribe_cpu_metrics()	CpuMetrics	CPU usage per-core and total
subscribe_cpu_telemetry()	CpuTelemetryMetrics	CPU power and temperature
subscribe_memory_metrics()	MemoryMetrics	System memory usage
subscribe_ups_updates()	dict	UPS state changes (raw)
subscribe_array_updates()	ArraySubscriptionUpdate	Array state and capacity changes
subscribe_temperature_metrics()	TemperatureMetrics	Temperature sensor updates

Models

System Models

• 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

Storage Models

• 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

Docker/VM Models

• 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 Models

• 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

Network Models (Deprecated)

• 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 Models

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

Subscription Models

• 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

Exceptions

Exception	Parent	Description
UnraidAPIError	Exception	Base exception for all API errors
UnraidConnectionError	UnraidAPIError	Connection failures
UnraidSSLError	UnraidConnectionError	SSL certificate verification failures
UnraidAuthenticationError	UnraidAPIError	Authentication failures (invalid API key)
UnraidTimeoutError	UnraidAPIError	Request timeout

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

Requirements

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

Development

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

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

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

License

MIT License - see LICENSE for details.

Contributing

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)

Links

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