unraid-api

An async Python client library for the Unraid GraphQL API (v4.21.0+, Unraid 7.1.4+).

Primary consumer: ha-unraid Home Assistant integration

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

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,
    UnraidTimeoutError,
)

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

API Reference

UnraidClient

Method	Description
test_connection()	Test if server is reachable
get_version()	Get Unraid and API version
query(query, variables)	Execute GraphQL query
mutate(mutation, variables)	Execute GraphQL mutation
start_container(id)	Start Docker container
stop_container(id)	Stop Docker container
start_vm(id)	Start VM
stop_vm(id)	Stop 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

Models

• SystemInfo - System information
• UnraidArray - Array state and disks
• ArrayDisk - Individual disk info
• ArrayCapacity - Capacity calculations
• DockerContainer - Container details
• VmDomain - VM details
• UPSDevice - UPS status
• Share - User share info
• PhysicalDisk - Physical disk info
• Notification - System notification

Requirements

• Python 3.11+
• Unraid 7.1.4+ with API 4.21.0+
• 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. All tests pass with 80%+ coverage
3. No linting errors (ruff check . && mypy src/)
4. GraphQL variables used (no string interpolation)

Links

• GraphQL API Reference
• Home Assistant Integration
• PyPI Package