### Quick Start: Connect and Get Version Info

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

A basic example demonstrating how to connect to the Unraid API using `UnraidClient`, test the connection, and retrieve version information. It utilizes `asyncio` for asynchronous operations and context management for the client session.

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

--------------------------------

### Manage Virtual Machines

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Examples for managing Virtual Machines (VMs) through the Unraid API. This includes starting and stopping a specific VM using the `start_vm` and `stop_vm` methods.

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

--------------------------------

### Install Project with Development Dependencies

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Installs the project in editable mode, including development dependencies. This is useful for making changes to the project and having them reflected immediately.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Control Docker Containers

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Examples of controlling Docker containers via the Unraid API. It shows how to start and stop a specified container using the `start_container` and `stop_container` methods.

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

--------------------------------

### Install unraid-api using pip

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Install the unraid-api Python package using pip. This command fetches and installs the latest version from PyPI, making the library available for use in your Python projects.

```bash
pip install unraid-api
```

--------------------------------

### Get Typed Installed Plugins (Python)

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves a list of installed plugins, with each plugin represented as a typed Pydantic model (Plugin). This allows iteration through plugins to display their names, versions, and module availability (API/CLI). Requires an active UnraidClient instance.

```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    plugins = await client.typed_get_plugins()

    for plugin in plugins:
        print(f"{plugin.name} v{plugin.version}")
        print(f"  Has API module: {plugin.hasApiModule}")
        print(f"  Has CLI module: {plugin.hasCliModule}")
```

--------------------------------

### GET /plugins

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves a list of installed plugins as a list of typed Plugin Pydantic models. This endpoint provides information about each plugin, including its name, version, and whether it has API or CLI modules.

```APIDOC
## GET /plugins

### Description
Returns installed plugins as a list of typed Plugin Pydantic models.

### Method
GET

### Endpoint
/plugins

### Parameters
None

### Request Example
```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    plugins = await client.typed_get_plugins()
    for plugin in plugins:
        print(f"{plugin.name} v{plugin.version}")
        print(f"  Has API module: {plugin.hasApiModule}")
        print(f"  Has CLI module: {plugin.hasCliModule}")
```

### Response
#### Success Response (200)
- **name** (str) - The name of the plugin.
- **version** (str) - The version of the plugin.
- **hasApiModule** (bool) - Indicates if the plugin has an API module.
- **hasCliModule** (bool) - Indicates if the plugin has a CLI module.

#### Response Example
```json
[
  {
    "name": "Dynamix",
    "version": "6.10.0",
    "hasApiModule": true,
    "hasCliModule": true
  },
  {
    "name": "NerdPack",
    "version": "1.2.0",
    "hasApiModule": false,
    "hasCliModule": true
  }
]
```
```

--------------------------------

### Control Virtual Machine Lifecycle (start, stop, force_stop)

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Manage the lifecycle of virtual machines, including starting, gracefully stopping, and forcefully stopping them. Requires an UnraidClient connection and the VM identifier.

```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Start a VM
    await client.start_vm("vm:windows-11")

    # Graceful shutdown (sends ACPI power button signal)
    await client.stop_vm("vm:windows-11")

    # Force stop (immediate power off)
    await client.force_stop_vm("vm:windows-11")
```

--------------------------------

### VM Lifecycle Management

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Control the start, stop, and force stop operations for virtual machines.

```APIDOC
## POST /vms/{vm_id}/start

### Description
Starts a specified virtual machine.

### Method
POST

### Endpoint
`/vms/{vm_id}/start`

### Parameters
#### Path Parameters
- **vm_id** (string) - Required - The ID or name of the VM to start (e.g., `vm:windows-11`).

## POST /vms/{vm_id}/stop

### Description
Gracefully stops a specified virtual machine by sending an ACPI power button signal.

### Method
POST

### Endpoint
`/vms/{vm_id}/stop`

### Parameters
#### Path Parameters
- **vm_id** (string) - Required - The ID or name of the VM to stop (e.g., `vm:windows-11`).

## POST /vms/{vm_id}/force_stop

### Description
Forcefully stops (powers off) a specified virtual machine immediately.

### Method
POST

### Endpoint
`/vms/{vm_id}/force_stop`

### Parameters
#### Path Parameters
- **vm_id** (string) - Required - The ID or name of the VM to force stop (e.g., `vm:windows-11`).
```

--------------------------------

### Get Services

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves system services as a list of raw dictionaries, offering basic information about each service.

```APIDOC
## get_services

### Description
Returns system services as a list of raw dictionaries.

### Method
GET

### Endpoint
/services

### Parameters
#### Query Parameters
- **format** (string) - Optional - Specifies the output format. Use 'raw' for dictionaries.

### Request Example
```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    services = await client.get_services()
    for s in services:
        print(f"{s['name']}: online={s['online']}")
```

### Response
#### Success Response (200)
- **services** (list) - A list of dictionaries, each representing a service with keys like 'name' and 'online'.

#### Response Example
```json
[
  {
    "name": "docker",
    "online": true
  }
]
```
```

--------------------------------

### Container Lifecycle Management

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Control the start, stop, and restart state of Docker containers.

```APIDOC
## POST /containers/{container_id}/start

### Description
Starts a specified Docker container.

### Method
POST

### Endpoint
`/containers/{container_id}/start`

### Parameters
#### Path Parameters
- **container_id** (string) - Required - The ID or name of the container to start (e.g., `container:plex`).

### Request Example
```json
{
  "container_id": "container:plex"
}
```

### Response
#### Success Response (200)
- **docker.start.state** (string) - The current state of the container after the operation.

#### Response Example
```json
{
  "docker": {
    "start": {
      "state": "running"
    }
  }
}
```

## POST /containers/{container_id}/stop

### Description
Stops a specified Docker container gracefully.

### Method
POST

### Endpoint
`/containers/{container_id}/stop`

### Parameters
#### Path Parameters
- **container_id** (string) - Required - The ID or name of the container to stop (e.g., `container:plex`).

### Request Example
```json
{
  "container_id": "container:plex"
}
```

### Response
#### Success Response (200)
- **docker.stop.state** (string) - The current state of the container after the operation.

#### Response Example
```json
{
  "docker": {
    "stop": {
      "state": "stopped"
    }
  }
}
```

## POST /containers/{container_id}/restart

### Description
Restarts a specified Docker container.

### Method
POST

### Endpoint
`/containers/{container_id}/restart`

### Parameters
#### Path Parameters
- **container_id** (string) - Required - The ID or name of the container to restart (e.g., `container:plex`).

### Request Example
```json
{
  "container_id": "container:plex"
}
```

### Response
#### Success Response (200)
- **docker.restart.state** (string) - The current state of the container after the operation.

#### Response Example
```json
{
  "docker": {
    "restart": {
      "state": "running"
    }
  }
}
```
```

--------------------------------

### Session Injection (Home Assistant)

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Example of how to inject an existing aiohttp.ClientSession for integration with frameworks like Home Assistant.

```APIDOC
## Session Injection (Home Assistant)

### Description
Demonstrates how to use an external `aiohttp.ClientSession` with `UnraidClient`, which is useful for integrating with applications like Home Assistant that manage their own sessions.

### Method
`UnraidClient(host, api_key, session=None, verify_ssl=True)`

### Endpoint
N/A (Client initialization)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **host** (str) - Required - The Unraid server hostname or IP address.
- **api_key** (str) - Required - Your Unraid API key.
- **session** (aiohttp.ClientSession) - Optional - An existing `aiohttp.ClientSession` instance to use. If provided, the client will not close this session upon exiting the context.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates. Defaults to `True`.

### Request Example
```python
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
```

### Response
#### Success Response (UnraidClient Instance)
- An instance of `UnraidClient` configured to use the provided session.
```

--------------------------------

### GET /get_version

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves Unraid server and API version information.

```APIDOC
## GET /get_version

Retrieves Unraid server and API version information.

### Method
GET

### Endpoint
/get_version

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    version = await client.get_version()
    print(f"Unraid: {version['unraid']}, API: {version['api']}")
    # Output: Unraid: 7.1.4, API: 4.21.0
```

### Response
#### Success Response (200)
- **unraid** (str) - Unraid server version
- **api** (str) - API version

#### Response Example
```json
{
  "unraid": "7.1.4",
  "api": "4.21.0"
}
```
```

--------------------------------

### Control Unraid Disk Array (start, stop)

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Manage the Unraid disk array by starting or stopping it. The stop operation is destructive and affects all services relying on array storage. Requires an UnraidClient connection.

```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Start the array
    result = await client.start_array()
    print(f"Array state: {result['array']['setState']['state']}")

    # Stop the array (WARNING: affects all storage-dependent services)
    result = await client.stop_array()
    print(f"Array state: {result['array']['setState']['state']}")
```

--------------------------------

### GET /get_system_metrics

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves CPU, memory, swap, and uptime metrics for monitoring. Returns a typed SystemMetrics Pydantic model.

```APIDOC
## GET /get_system_metrics

Retrieves CPU, memory, swap, and uptime metrics for monitoring. Returns a typed SystemMetrics Pydantic model.

### Method
GET

### Endpoint
/get_system_metrics

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    metrics = await client.get_system_metrics()
    print(f"CPU Usage: {metrics.cpu_percent}%")
    print(f"CPU Temperature: {metrics.cpu_temperature}°C")
    print(f"CPU Power: {metrics.cpu_power}W")
    print(f"Memory Usage: {metrics.memory_percent}%")
    print(f"Memory Used: {metrics.memory_used / (1024**3):.1f} GB")
    print(f"Swap Usage: {metrics.swap_percent}%")
    print(f"System Uptime: {metrics.uptime}")
```

### Response
#### Success Response (200)
- **cpu_percent** (float) - CPU usage percentage
- **cpu_temperature** (float) - CPU temperature in Celsius
- **cpu_power** (float) - CPU power consumption in Watts
- **memory_percent** (float) - Memory usage percentage
- **memory_used** (int) - Memory used in bytes
- **swap_percent** (float) - Swap usage percentage
- **uptime** (str) - System uptime string

#### Response Example
```json
{
  "cpu_percent": 15.5,
  "cpu_temperature": 45.2,
  "cpu_power": 55.0,
  "memory_percent": 60.3,
  "memory_used": 1234567890,
  "swap_percent": 5.1,
  "uptime": "10 days, 5 hours, 30 minutes"
}
```
```

--------------------------------

### GET /get_server_info

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Returns comprehensive server identification data as a Pydantic model, useful for Home Assistant device registration.

```APIDOC
## GET /get_server_info

Returns comprehensive server identification data as a Pydantic model, useful for Home Assistant device registration.

### Method
GET

### Endpoint
/get_server_info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    info = await client.get_server_info()
    print(f"Hostname: {info.hostname}")
    print(f"UUID: {info.uuid}")
    print(f"Model: {info.model}")           # e.g., "Unraid 7.1.4"
    print(f"CPU: {info.cpu_brand}")
    print(f"Cores/Threads: {info.cpu_cores}/{info.cpu_threads}")
    print(f"License: {info.license_type}")  # Basic, Plus, Pro, etc.
    print(f"LAN IP: {info.lan_ip}")
    print(f"Local URL: {info.local_url}")
```

### Response
#### Success Response (200)
- **hostname** (str) - Server hostname
- **uuid** (str) - Server UUID
- **model** (str) - Server model (e.g., "Unraid 7.1.4")
- **cpu_brand** (str) - CPU brand string
- **cpu_cores** (int) - Number of CPU cores
- **cpu_threads** (int) - Number of CPU threads
- **license_type** (str) - License type (e.g., "Basic", "Plus", "Pro")
- **lan_ip** (str) - Local IP address
- **local_url** (str) - Local URL of the Unraid server

#### Response Example
```json
{
  "hostname": "Tower",
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "model": "Unraid 7.1.4",
  "cpu_brand": "Intel(R) Core(TM) i7-8700K CPU @ 3.70GHz",
  "cpu_cores": 6,
  "cpu_threads": 12,
  "license_type": "Plus",
  "lan_ip": "192.168.1.100",
  "local_url": "http://192.168.1.100"
}
```
```

--------------------------------

### GraphQL Query: Get System Information

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Retrieves detailed system information, including CPU, memory, OS, and Unraid version details.

```graphql
query {
  info {
    time
    os { hostname uptime kernel }
    cpu { brand cores threads }
    memory { layout { size type clockSpeed manufacturer } }
    versions { core { unraid api kernel } }
    baseboard { manufacturer model memMax memSlots }
    display { theme unit warning critical }
  }
}
```

--------------------------------

### GraphQL Query: Get System Variables

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Retrieves core system configuration variables such as hostname, time zone, and port settings.

```graphql
query {
  vars {
    version
    name
    timeZone
    useSsl
    port
    portssl
  }
}
```

--------------------------------

### Typed Get Services

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves system services as a list of typed Service Pydantic models, providing detailed information about each service.

```APIDOC
## typed_get_services

### Description
Returns system services as a list of typed Service Pydantic models.

### Method
GET

### Endpoint
/services

### Parameters
#### Query Parameters
- **format** (string) - Optional - Specifies the output format. Use 'typed' for Pydantic models.

### Request Example
```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    services = await client.typed_get_services()
    for service in services:
        status = "Online" if service.online else "Offline"
        print(f"{service.name}: {status} (v{service.version})")
```

### Response
#### Success Response (200)
- **services** (list) - A list of Service Pydantic models, each containing details like name, version, and online status.

#### Response Example
```json
[
  {
    "name": "docker",
    "version": "6.10.0",
    "online": true
  }
]
```
```

--------------------------------

### Get Raw Docker Containers - Python

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves all Docker containers as a list of raw dictionaries. Requires an UnraidClient instance.

```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    containers = await client.get_containers()

    for c in containers:
        name = c['names'][0].lstrip('/') if c['names'] else c['id']
        print(f"{name}: {c['state']} - {c['status']}")
```

--------------------------------

### Setup and Development Commands for Unraid API

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/CLAUDE.md

This section details essential bash commands for setting up the development environment, running tests with coverage, linting, formatting, and type checking. It also covers pre-commit hook execution for maintaining code quality.

```bash
# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run all tests with coverage
pytest tests/ -v --cov=src/unraid_api

# Run a single test file
pytest tests/test_client.py -v

# Run a single test
pytest tests/test_client.py::TestClassName::test_method_name -v

# Linting and formatting
ruff check .
ruff format .
mypy src/

# Pre-commit hooks (runs ruff, mypy, security checks)
pre-commit run --all-files
```

--------------------------------

### Initialize UnraidClient in Python

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Demonstrates how to initialize the UnraidClient, including basic context manager usage, advanced custom settings, and injecting an external aiohttp session for Home Assistant integration. Supports automatic SSL detection and remote access redirection.

```python
import asyncio
from unraid_api import UnraidClient

# Basic usage with context manager (recommended)
async def main():
    async with UnraidClient("192.168.1.100", "your-api-key") as client:
        if await client.test_connection():
            print("Connected to Unraid!")

asyncio.run(main())

# Advanced initialization with custom settings
client = UnraidClient(
    host="192.168.1.100",      # Server hostname or IP
    api_key="your-api-key",    # Unraid API key with ADMIN role
    http_port=80,              # HTTP port for redirect discovery
    https_port=443,            # HTTPS port
    verify_ssl=False,          # Disable SSL verification for self-signed certs
    timeout=30,                # Request timeout in seconds
)

# Home Assistant session injection
import aiohttp

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

```

--------------------------------

### Create Virtual Environment and Activate

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

This snippet demonstrates how to create a Python virtual environment using the 'venv' module and then activate it. This isolates project dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
```

--------------------------------

### GET /cloud / GET /connect / GET /remote_access

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Access Unraid Connect cloud settings and remote access configuration. This group of endpoints provides information about API key validity, cloud status, remote access type, and specific remote access settings.

```APIDOC
## GET /cloud / GET /connect / GET /remote_access

### Description
Access Unraid Connect cloud settings and remote access configuration.

### Method
GET

### Endpoint
/cloud
/connect
/remote_access

### Parameters
None

### Request Example
```python
from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Cloud settings
    cloud = await client.typed_get_cloud()
    print(f"API Key Valid: {cloud.apiKey.valid if cloud.apiKey else 'N/A'}")
    print(f"Cloud Status: {cloud.cloud.status if cloud.cloud else 'N/A'}")

    # Connect status
    connect = await client.typed_get_connect()
    if connect.dynamicRemoteAccess:
        print(f"Remote Access Type: {connect.dynamicRemoteAccess.runningType}")

    # Remote access settings
    remote = await client.typed_get_remote_access()
    print(f"Access Type: {remote.accessType}")
    print(f"Forward Type: {remote.forwardType}")
    print(f"Port: {remote.port}")
```

### Response
#### Success Response (200)
- **cloud** (object) - Cloud settings.
  - **apiKey** (object) - API key details.
    - **valid** (bool) - Whether the API key is valid.
  - **cloud** (object) - Cloud status details.
    - **status** (str) - The status of the Unraid Connect service.
- **connect** (object) - Connection status.
  - **dynamicRemoteAccess** (object) - Dynamic remote access details.
    - **runningType** (str) - The type of running remote access.
- **remoteAccess** (object) - Remote access configuration.
  - **accessType** (str) - The type of remote access configured.
  - **forwardType** (str) - The port forwarding type.
  - **port** (int) - The configured port for remote access.

#### Response Example
```json
{
  "cloud": {
    "apiKey": {
      "valid": true
    },
    "cloud": {
      "status": "Connected"
    }
  },
  "connect": {
    "dynamicRemoteAccess": {
      "runningType": "OpenVPN"
    }
  },
  "remoteAccess": {
    "accessType": "Dynamic DNS",
    "forwardType": "Manual",
    "port": 443
  }
}
```
```

--------------------------------

### Control Docker Container Lifecycle (start, stop, restart)

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Manage the lifecycle of Docker containers using start, stop, and restart operations. Requires an active UnraidClient connection. Accepts container IDs or names.

```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Start a container
    result = await client.start_container("container:plex")
    print(f"Container state: {result['docker']['start']['state']}")

    # Stop a container
    result = await client.stop_container("container:plex")
    print(f"Container state: {result['docker']['stop']['state']}")

    # Note: Container IDs use the format "container:<name>" or "container:<id>"
```

--------------------------------

### UnraidClient Initialization

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Initialize the UnraidClient to connect to your Unraid server. Supports context manager usage, custom ports, SSL verification settings, and external session injection for Home Assistant.

```APIDOC
## UnraidClient Initialization

The main client class for connecting to an Unraid server. Supports context manager usage for automatic session cleanup, custom ports, SSL verification settings, and external session injection for Home Assistant integration.

### Method
Initialization

### Parameters
#### Path Parameters
- **host** (str) - Required - Server hostname or IP
- **api_key** (str) - Required - Unraid API key with ADMIN role

#### Query Parameters
- **http_port** (int) - Optional - HTTP port for redirect discovery (default: 80)
- **https_port** (int) - Optional - HTTPS port (default: 443)
- **verify_ssl** (bool) - Optional - Disable SSL verification for self-signed certs (default: True)
- **timeout** (int) - Optional - Request timeout in seconds (default: 30)
- **session** (aiohttp.ClientSession) - Optional - External aiohttp session for Home Assistant integration

### Request Example
```python
import asyncio
from unraid_api import UnraidClient

# Basic usage with context manager (recommended)
async def main():
    async with UnraidClient("192.168.1.100", "your-api-key") as client:
        if await client.test_connection():
            print("Connected to Unraid!")

asyncio.run(main())

# Advanced initialization with custom settings
client = UnraidClient(
    host="192.168.1.100",      # Server hostname or IP
    api_key="your-api-key",    # Unraid API key with ADMIN role
    http_port=80,              # HTTP port for redirect discovery
    https_port=443,            # HTTPS port
    verify_ssl=False,          # Disable SSL verification for self-signed certs
    timeout=30,                # Request timeout in seconds
)

# Home Assistant session injection
import aiohttp

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

### Response
#### Success Response (200)
- **client** (UnraidClient) - An instance of the UnraidClient class.
```

--------------------------------

### Control Unraid Array Operations

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Demonstrates various array operations supported by the Unraid API, including starting and stopping the array, managing parity checks (start, pause, resume, cancel), and controlling disk spin states (up/down).

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

--------------------------------

### Inject aiohttp Session for Home Assistant Integration

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Shows how to integrate `unraid-api` with Home Assistant by injecting an existing `aiohttp.ClientSession`. This allows for reusing the session and prevents the client from closing it, ensuring proper resource management.

```python
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
```

--------------------------------

### Get Notifications

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves notifications with support for filtering by type and pagination.

```APIDOC
## get_notifications

### Description
Returns notifications with filtering and pagination support.

### Method
GET

### Endpoint
/notifications

### Parameters
#### Query Parameters
- **notification_type** (string) - Required - Type of notifications to retrieve (e.g., 'UNREAD', 'ARCHIVE').
- **limit** (integer) - Optional - Maximum number of notifications to return.
- **offset** (integer) - Optional - Number of notifications to skip before starting to collect.

### Request Example
```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Get unread notifications
    notifications = await client.get_notifications(
        notification_type="UNREAD",
        limit=50,
        offset=0
    )
    for n in notifications.get("list", []):
        print(f"[{n['importance']}] {n['title']}")
```

### Response
#### Success Response (200)
- **list** (list) - A list of notification dictionaries, each containing 'importance', 'title', 'description', and 'timestamp'.

#### Response Example
```json
{
  "list": [
    {
      "importance": "WARNING",
      "title": "High disk usage",
      "description": "Disk 5 is at 90% capacity.",
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Docker Mutations

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Mutations for managing Docker containers, including starting, stopping, pausing, removing, and updating.

```APIDOC
## Docker Mutations

### Description
Manage Docker containers on your Unraid server. This includes starting, stopping, pausing, unpausing, removing containers, updating them to the latest image, and configuring auto-start behavior.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **mutation** (String!) - The GraphQL mutation string.

### Request Example
```graphql
# Start container
mutation {
  docker {
    start(id: "container:abc123") { id names state status }
  }
}

# Stop container
mutation {
  docker {
    stop(id: "container:abc123") { id names state status }
  }
}

# Pause/unpause container
mutation {
  docker {
    pause(id: "container:abc123") { id state }
    unpause(id: "container:abc123") { id state }
  }
}

# Remove container
mutation {
  docker {
    removeContainer(id: "container:abc123", withImage: false)
  }
}

# Update container to latest image
mutation {
  docker {
    updateContainer(id: "container:abc123") { id names image }
  }
}

# Update multiple containers
mutation {
  docker {
    updateContainers(ids: ["container:abc", "container:def"]) { id names }
  }
}

# Update all containers
mutation {
  docker {
    updateAllContainers { id names }
  }
}

# Update auto-start configuration
mutation {
  docker {
    updateAutostartConfiguration(entries: [
      { id: "container:abc", autoStart: true, wait: 5 }
    ])
  }
}
```

### Response
#### Success Response (200)
- **data** (Object) - The response data containing the result of the mutation.
  - **docker** (Object)
    - **start** (Object)
      - **id** (String)
      - **names** (Array<String>)
      - **state** (String)
      - **status** (String)
    - **stop** (Object)
      - **id** (String)
      - **names** (Array<String>)
      - **state** (String)
      - **status** (String)
    - **pause** (Object)
      - **id** (String)
      - **state** (String)
    - **unpause** (Object)
      - **id** (String)
      - **state** (String)
    - **removeContainer** (Boolean)
    - **updateContainer** (Object)
      - **id** (String)
      - **names** (Array<String>)
      - **image** (String)
    - **updateContainers** (Array<Object>)
      - **id** (String)
      - **names** (Array<String>)
    - **updateAllContainers** (Array<Object>)
      - **id** (String)
      - **names** (Array<String>)
    - **updateAutostartConfiguration** (Boolean)

#### Response Example
```json
{
  "data": {
    "docker": {
      "start": {
        "id": "container:abc123",
        "names": ["/my-container"],
        "state": "running",
        "status": "exited"
      }
    }
  }
}
```
```

--------------------------------

### Array Mutations

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Mutations for controlling the Unraid array, including starting, stopping, adding/removing disks, and mounting/unmounting.

```APIDOC
## Array Mutations

### Description
Provides mutations to control the state of the Unraid array, such as starting, stopping, adding or removing disks, and mounting or unmounting individual disks.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **mutation** (String!) - The GraphQL mutation string.

### Request Example
```graphql
# Start array
mutation {
  array {
    setState(input: { desiredState: START }) { state }
  }
}

# Stop array
mutation {
  array {
    setState(input: { desiredState: STOP }) { state }
  }
}

# Add disk to array
mutation {
  array {
    addDiskToArray(input: { id: "disk:abc", slot: 1 }) { state }
  }
}

# Remove disk from array (array must be stopped)
mutation {
  array {
    removeDiskFromArray(input: { id: "disk:abc" }) { state }
  }
}

# Mount/unmount disk
mutation {
  array {
    mountArrayDisk(id: "disk:1") { id name isSpinning }
    unmountArrayDisk(id: "disk:1") { id name isSpinning }
  }
}

# Clear disk statistics
mutation {
  array {
    clearArrayDiskStatistics(id: "disk:1")
  }
}
```

### Response
#### Success Response (200)
- **data** (Object) - The response data containing the result of the mutation.
  - **array** (Object)
    - **setState** (Object)
      - **state** (String) - The new state of the array (e.g., "STARTING", "STOPPED").
    - **addDiskToArray** (Object)
      - **state** (String) - The state of the array after adding the disk.
    - **removeDiskFromArray** (Object)
      - **state** (String) - The state of the array after removing the disk.
    - **mountArrayDisk** (Object)
      - **id** (String)
      - **name** (String)
      - **isSpinning** (Boolean)
    - **unmountArrayDisk** (Object)
      - **id** (String)
      - **name** (String)
      - **isSpinning** (Boolean)

#### Response Example
```json
{
  "data": {
    "array": {
      "setState": {
        "state": "STARTING"
      }
    }
  }
}
```
```

--------------------------------

### Authentication API Key

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Demonstrates how to create a new API key with specified roles and permissions.

```APIDOC
## POST /graphql

### Description
Creates a new API key for the Unraid server.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Query Parameters
None

#### Request Body
##### `apiKey.create` (Mutation)
- **input** (object) - Required - Input object for creating an API key.
  - **name** (String!) - Required - The name of the API key.
  - **description** (String) - Optional - A description for the API key.
  - **roles** (Array<Role!>) - Required - An array of roles to assign to the API key.

### Request Example
```graphql
mutation {
  apiKey {
    create(input: {
      name: "My API Key"
      description: "API key for my application"
      roles: [ADMIN]
    }) {
      id
      key
      name
      roles
      permissions
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object)
  - **apiKey.create** (object)
    - **id** (PrefixedID) - The unique identifier of the created API key.
    - **key** (String) - The generated API key.
    - **name** (String) - The name of the API key.
    - **roles** (Array<Role>) - The roles assigned to the API key.
    - **permissions** (Array<Resource>) - The permissions associated with the API key.

#### Response Example
```json
{
  "data": {
    "apiKey": {
      "create": {
        "id": "server123:apiKey456",
        "key": "your_generated_api_key_here",
        "name": "My API Key",
        "roles": ["ADMIN"],
        "permissions": ["ARRAY", "DISK", "DOCKER", "VMS"]
      }
    }
  }
}
```
```

--------------------------------

### GraphQL Query: Get Virtual Machine Domains

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Retrieves a list of virtual machine domains and their current states.

```graphql
query {
  vms {
    domains {
      id name state
    }
  }
}
```

--------------------------------

### Complete System Status Query (GraphQL)

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

An example GraphQL query to retrieve comprehensive system status information, including online status, OS details, CPU/memory metrics, array status, Docker container info, VM domains, notification counts, and UPS status.

```graphql
query SystemStatus {
  online
  info {
    os { hostname uptime }
    cpu { brand cores threads }
    versions { core { unraid api } }
  }
  metrics {
    cpu { percentTotal }
    memory { percentTotal }
  }
  array {
    state
    capacity { kilobytes { free used total } }
    parityCheckStatus { status progress running }
  }
  docker {
    containers { names state isUpdateAvailable }
  }
  vms {
    domains { name state }
  }
  notifications {
    overview { unread { alert warning } }
  }
  upsDevices {
    status
    battery { chargeLevel }
  }
}
```

--------------------------------

### GraphQL Query: Get Registration Information

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Fetches the current registration status and expiration date of the Unraid system.

```graphql
query {
  registration {
    type
    state
    expiration
  }
}
```

--------------------------------

### VM Management

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/README.md

Methods for managing Virtual Machines via the Unraid API.

```APIDOC
## VM Management

### Description
Control Virtual Machines including starting and stopping them.

### Method
`start_vm(vm_name)`

### Endpoint
N/A (Internal client method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vm_name** (str) - Required - The name or ID of the VM to start (e.g., "vm:windows-11").

### Request Example
```python
async with UnraidClient(host, api_key) as client:
    await client.start_vm("vm:windows-11")
```

### Response
#### Success Response (None)
- No specific response body on success.

### Method
`stop_vm(vm_name)`

### Endpoint
N/A (Internal client method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vm_name** (str) - Required - The name or ID of the VM to stop (e.g., "vm:windows-11").

### Request Example
```python
async with UnraidClient(host, api_key) as client:
    await client.stop_vm("vm:windows-11")
```

### Response
#### Success Response (None)
- No specific response body on success.
```

--------------------------------

### Get UPS Status

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves the status of UPS devices as a list of raw dictionaries.

```APIDOC
## get_ups_status

### Description
Returns UPS device status as a list of raw dictionaries.

### Method
GET

### Endpoint
/ups/status

### Parameters
None

### Request Example
```python
async with UnraidClient("192.168.1.100", "your-api-key") as client:
    ups_list = await client.get_ups_status()
    for ups in ups_list:
        print(f"{ups['name']}: {ups['status']}")
```

### Response
#### Success Response (200)
- **ups_list** (list) - A list of dictionaries, each representing a UPS with its name and status.

#### Response Example
```json
[
  {
    "name": "ups1",
    "status": "ONLINE",
    "battery": {
      "chargeLevel": 95
    }
  }
]
```
```

--------------------------------

### Virtual Machine Management (Raw)

Source: https://context7.com/ruaan-deysel/unraid-api/llms.txt

Retrieves a list of all virtual machines, returned as raw dictionaries.

```APIDOC
## GET /vms

### Description
Retrieves all virtual machines, with each VM represented as a raw dictionary.

### Method
GET

### Endpoint
`/vms`

### Response
#### Success Response (200)
- **vms** (array) - A list of dictionaries, each containing details about a virtual machine.
  - **name** (string) - The name of the VM.
  - **id** (string) - The unique identifier of the VM.
  - **state** (string) - The current state of the VM (e.g., 'running', 'stopped').

#### Response Example
```json
[
  {
    "name": "Windows 11 VM",
    "id": "vm:windows-11",
    "state": "running"
  },
  {
    "name": "Ubuntu Server",
    "id": "vm:ubuntu-server",
    "state": "stopped"
  }
]
```
```

--------------------------------

### GraphQL Query: Get Docker Container Update Statuses

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Checks the update availability status for all Docker containers on the system.

```graphql
query {
  docker {
    containerUpdateStatuses {
      name updateStatus
    }
  }
}
```

--------------------------------

### GraphQL Query: Get Physical Disks

Source: https://github.com/ruaan-deysel/unraid-api/blob/main/UNRAIDAPI.md

Fetches details about all physical disks connected to the Unraid system, including their partitions.

```graphql
query {
  disks {
    device name vendor size
    interfaceType smartStatus temperature
    isSpinning
    partitions { name fsType size }
  }
}
```