unraid-graphql-api

Unraid GraphQL API

The official GraphQL API is built into Unraid 7.2+ (no plugin required). On pre-7.2 systems, install the "Unraid Connect" plugin from Community Applications.

Endpoint

http://SERVER_IP/graphql

The backend is a NestJS application on Fastify with Apollo Server, binding internally on port 3001.

Authentication

Three authentication methods are supported:

Method	Header/Mechanism	Use Case
API Key	x-api-key: YOUR_KEY	Scripts, CI/CD, external tools
Session Cookie	WebGUI login cookie	Browser-based access
SSO/OIDC	OAuth flow	Enterprise/Unraid Connect

Create an API Key via CLI

KEY_DATA=$(unraid-api apikey --create --name "deploy key" --roles ADMIN --json)
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')

Test Authentication

curl -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "query { array { state } }"}' http://SERVER_IP/graphql

RBAC Permissions

Authorization uses the Casbin RBAC engine with a Resource:Action pattern.

Permission	Grants
DOCKER:READ_ANY	List containers, stats, logs
DOCKER:UPDATE_ANY	Start, stop, restart containers
VMS:READ_ANY	List VMs, status
VMS:UPDATE_ANY	Start, stop, pause VMs
ARRAY:READ_ANY	Array state, disk info
ARRAY:UPDATE_ANY	Start/stop array, parity ops
ARRAY:DELETE_ANY	Remove disks
SHARES:READ_ANY	List shares
NOTIFICATIONS:READ_ANY	Read notifications

PrefixedID Format

Resource IDs use a serverId:resourceId format:

• vm:abc123 -- virtual machine
• container:xyz789 -- Docker container

Pass these IDs to mutations and queries that accept resource identifiers.

Common Queries

Query	Returns
{ info { os { hostname version uptime } } }	System info
{ array { state capacity { disks { name size } } } }	Array status and disks
{ vms { domain { name uuid state } } }	All VMs with state
{ docker { containers { id names state status } } }	All containers
{ shares { name free size } }	User shares
{ disks { id device temp status } }	Physical disks
{ notifications { subject description timestamp } }	System notifications

Common Mutations

VM Lifecycle

mutation { vm { start(id: "vm:UUID") } }
mutation { vm { stop(id: "vm:UUID") } }
mutation { vm { forceStop(id: "vm:UUID") } }
mutation { vm { pause(id: "vm:UUID") } }
mutation { vm { resume(id: "vm:UUID") } }
mutation { vm { reboot(id: "vm:UUID") } }
mutation { vm { reset(id: "vm:UUID") } }

IMPORTANT: No mutation exists for creating new VMs. VM provisioning requires libvirt directly. See the vm-provisioning skill.

Container Lifecycle

mutation { docker { start(id: "container:ID") } }
mutation { docker { stop(id: "container:ID") } }
mutation { docker { restart(id: "container:ID") } }
mutation { docker { pause(id: "container:ID") } }
mutation { docker { unpause(id: "container:ID") } }
mutation { docker { remove(id: "container:ID") } }

Array and Parity

mutation { array { start } }
mutation { array { stop } }
mutation { parity { start(correct: false) } }
mutation { parity { pause } }
mutation { parity { resume } }
mutation { parity { cancel } }

WebSocket Subscriptions

Use the graphql-ws protocol on the same /graphql endpoint for real-time data. Connect with a WebSocket client that supports graphql-transport-ws:

subscription { dockerContainerStats { id cpuPercent memUsage } }
subscription { notifications { subject description importance } }

GraphQL Sandbox

Enable the Apollo Studio interactive explorer for schema discovery:

unraid-api developer --sandbox true

Access the sandbox at http://SERVER_IP/graphql in a browser. Disable when done:

unraid-api developer --sandbox false

Python Client

Install the typed Python client with Pydantic models:

pip install unraid-api

from unraid_api import UnraidClient

async with UnraidClient("192.168.1.100", "your-api-key") as client:
    # Container operations
    containers = await client.get_docker_containers()
    await client.start_container("container:plex")

    # VM operations
    vms = await client.get_vms()
    await client.start_vm("vm:abc123")

    # System info
    info = await client.get_system_info()

Raw GraphQL with curl

# Query
curl -s -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "{ vms { domain { name uuid state } } }"}' \
  http://SERVER_IP/graphql | jq

# Mutation
curl -s -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "mutation { vm { start(id: \"vm:UUID\") } }"}' \
  http://SERVER_IP/graphql | jq

MCP Server Integration

The MCP tools provided by this plugin handle most API interactions automatically. Use direct GraphQL calls only when the MCP tools do not cover a specific operation or when building custom integrations.

Limitations

• No VM creation mutation -- only lifecycle operations on existing VMs
• No snapshot create/list/restore mutations exposed via GraphQL
• WebSocket subscription schema completeness requires sandbox mode to fully discover
• CSRF token handling for emcmd calls in Unraid 7.x is inconsistently documented