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

    # Native restart when available; stop/wait/start on older schemas
    await client.restart_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")

For an encrypted array, replace start_array() above with start_array(decryption_password=password) or start_array(decryption_keyfile=keyfile_contents). Keyfiles are data URLs or raw base64 contents, not paths. Decryption values require an HTTPS connection; HTTP destinations and redirects are rejected before transmitting them. Certificate verification must be enabled. For private certificates, configure system trust roots or SSL_CERT_FILE/SSL_CERT_DIR; encrypted starts enforce that trust even when using an injected session. Configure the canonical HTTPS hostname and port for encrypted starts: they bypass HTTP discovery, ignore cached destinations, and reject redirects pointing at a different server or port.

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

A subscription that receives no message for timeout * 10 seconds (300 s with the default timeout=30) raises UnraidTimeoutError. This is normal for rare events on a quiet server, such as notifications or UPS changes; catch it and reconnect.

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

High-Level Typed Methods (Pydantic Models)

Standby-safe temperature metrics

Unraid API >= 4.37.6 respects disk standby when reading metrics.temperature or streaming systemMetricsTemperature. Earlier APIs wake sleeping disks. At setup, call check_compatibility() (or get_version()) once and pass the result to supports_standby_safe_temperature_metrics(version). For ha-unraid and other consumers, a True result allows polling get_system_metrics() and enabling temperature sensors. Otherwise use get_system_metrics_safe().

version = await client.check_compatibility()
if await client.supports_standby_safe_temperature_metrics(version):
    metrics = await client.get_system_metrics()
else:
    metrics = await client.get_system_metrics_safe()

The helper compares only the API version, fails closed on unknown versions and does not cache. Recheck the version after reconnecting or upgrading the API plugin. Continue to avoid polling get_physical_disks(), even with include_smart=False: that query still wakes disks on 4.37.6 pending unraid/api#2105. Use get_array_disks().

restart_container() returns raw docker.restart data on the native path or docker.start data on the fallback path. Its delay argument applies only to the fallback. If introspection fails, permissive capabilities optimistically attempt native restart. typed_get_vms() requests uuid only when introspection confirms support; unknown schemas omit it to preserve VM listing.

Plugin and language installs modify the server. Follow their returned operation with subscribe_plugin_install_updates(operation.id). remove_array_disk() emits DeprecationWarning and rejects servers without the retired mutation; use the Unraid Core storage workflow instead.

Raw Data Methods

Control Methods

Subscription Methods (WebSocket)

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, optional uuid)
• 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

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

Requirements

• Python 3.11 or later, tested on 3.11–3.15
• Unraid 7.2.4+ with latest Unraid API
• API key with appropriate permissions

Development

# Clone repository
git clone https://github.com/tinkerologie/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/

License

Apache License 2.0 - see LICENSE for details. Earlier releases were MIT licensed; see NOTICE.

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