Artifacts/unraid-mcp
2
0
Fork 0
forked from HomeLab/unraid-mcp
Code Pull Requests Actions Packages Releases 5 Activity
Files
0.0.3
unraid-mcp/docs/research/unraid-api-crawl.md

40 KiB
Raw Permalink Blame History

Unraid API Documentation Crawl - Complete Content

Date: 2026-02-07 Source: Firecrawl deep crawl of official Unraid documentation, blog, and community resources Vector DB: All content auto-embedded to Qdrant (firecrawl collection)

Table of Contents

  1. API Documentation (docs.unraid.net/API/)
  2. Complete GraphQL Schema
  3. Unraid Connect Documentation
  4. Release Notes (API-Relevant)
  5. Blog Posts
  6. Community Resources
  7. Source URLs Index

1. API Documentation

1.1 API Overview

Source: https://docs.unraid.net/API/

Starting with Unraid 7.2, the API comes built into the operating system -- no plugin installation required.

The Unraid API provides a GraphQL interface for programmatic interaction with your Unraid server. It enables automation, monitoring, and integration capabilities through a modern, strongly-typed API with:

  • Multiple authentication methods (API keys, session cookies, and SSO/OIDC)
  • Comprehensive system coverage
  • Built-in developer tools

Availability

Native integration (Unraid 7.2+):

  • No plugin installation required
  • Automatically available on system startup
  • Deep system integration
  • Access through Settings > Management Access > API

Plugin installation (Pre-7.2 and Advanced Users):

  1. Install the Unraid Connect plugin from Community Applications
  2. Configure the plugin
  3. Access API functionality through the GraphQL Sandbox

The Unraid Connect plugin provides the API for pre-7.2 versions. You do NOT need to sign in to Unraid Connect to use the API locally. Installing the plugin on Unraid 7.2+ gives you access to newer API features before they are included in OS releases.

Get Started (Unraid 7.2+)

  1. The API is already installed and running.
  2. Access settings at Settings > Management Access > API.
  3. Enable the GraphQL Sandbox for development.
  4. Create your first API key.
  5. Start making GraphQL queries!

Get Started (Pre-7.2 Versions)

  1. Install the Unraid Connect plugin from Community Applications.
  2. No Unraid Connect login required for local API access.
  3. Configure the plugin settings.
  4. Enable the GraphQL Sandbox.
  5. Start exploring the API!

1.2 How to Use the API

Source: https://docs.unraid.net/API/how-to-use-the-api/

The Unraid API provides a GraphQL interface that allows you to interact with your Unraid server. This guide covers authentication, common queries, and usage patterns.

Enabling the GraphQL Sandbox

Live Documentation:

  • View the complete API schema and documentation at Apollo GraphQL Studio (requires authentication; may not be publicly accessible)

WebGUI method (recommended):

  1. Navigate to Settings > Management Access > Developer Options
  2. Enable the GraphQL Sandbox toggle
  3. Access the GraphQL playground at: http://YOUR_SERVER_IP/graphql

CLI method:

unraid-api developer --sandbox true

Or use interactive mode:

unraid-api developer

Authentication

Most queries and mutations require authentication. You can authenticate using:

  1. API Keys -- For programmatic access
  2. Cookies -- Automatic when signed in to the WebGUI
  3. SSO/OIDC -- When configured with external providers

Managing API keys (WebGUI): Navigate to Settings > Management Access > API Keys to:

  • View existing API keys
  • Create new API keys
  • Manage permissions and roles
  • Revoke or regenerate keys

Managing API keys (CLI):

unraid-api apikey --create

Using API keys: Include the generated API key in your GraphQL requests as a header:

{
    "x-api-key": "YOUR_API_KEY"
}

Available Schemas

The API provides access to:

  • System information: CPU, memory, OS info, system status and health, baseboard and hardware info
  • Array management: Array status and configuration, start/stop operations, disk status and health, parity checks
  • Docker management: List and manage Docker containers, monitor container status, manage Docker networks
  • Remote access: Configure and manage remote access settings, SSO configuration, allowed origins

Example Queries

Check system status:

query {
    info {
        os {
            platform
            distro
            release
            uptime
        }
        cpu {
            manufacturer
            brand
            cores
            threads
        }
    }
}

Monitor array status:

query {
    array {
        state
        capacity {
            disks {
                free
                used
                total
            }
        }
        disks {
            name
            size
            status
            temp
        }
    }
}

List Docker containers:

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

Schema Types

Base types: Node (interface for objects with unique IDs), JSON (complex JSON data), DateTime (timestamp values), Long (64-bit integers)

Resource types: Array (array and disk management), Docker (container and network management), Info (system information), Config (server configuration), Connect (remote access settings)

Available roles: admin (full access), connect (remote access features), guest (limited read access)

Error Handling

The API returns standard GraphQL errors:

{
  "errors": [
    {
      "message": "Error description",
      "locations": [...],
      "path": [...]
    }
  ]
}

The API implements rate limiting to prevent abuse.

1.3 CLI Reference

Source: https://docs.unraid.net/API/cli/

All commands follow the pattern: unraid-api <command> [options].

Service Management

Start:

unraid-api start [--log-level <level>]
# Levels: trace|debug|info|warn|error|fatal
# Alternative: LOG_LEVEL=trace unraid-api start

Stop:

unraid-api stop [--delete]
# --delete: Optional. Delete the PM2 home directory.

Restart:

unraid-api restart [--log-level <level>]

Logs:

unraid-api logs [-l <lines>]
# -l, --lines: Number of lines to tail (default: 100)

Configuration Commands

View config:

unraid-api config

Switch environment:

unraid-api switch-env [-e <environment>]
# -e: production|staging

Developer mode:

unraid-api developer                       # Interactive prompt
unraid-api developer --sandbox true        # Enable GraphQL sandbox
unraid-api developer --sandbox false       # Disable GraphQL sandbox
unraid-api developer --enable-modal        # Enable modal testing tool
unraid-api developer --disable-modal       # Disable modal testing tool

Also available via WebGUI: Settings > Management Access > Developer Options

API Key Management

unraid-api apikey [options]

Options:

  • --name <name>: Name of the key
  • --create: Create a new key
  • -r, --roles <roles>: Comma-separated list of roles
  • -p, --permissions <permissions>: Comma-separated list of permissions
  • -d, --description <description>: Description for the key

Also available via WebGUI: Settings > Management Access > API Keys

SSO (Single Sign-On) Management

unraid-api sso                    # Base command
unraid-api sso add-user           # Add SSO user (aliases: add, a)
unraid-api sso remove-user        # Remove SSO user (aliases: remove, r)
unraid-api sso list-users         # List SSO users (aliases: list, l)
unraid-api sso validate-token <token>  # Validate SSO token (aliases: validate, v)

Report Generation

unraid-api report [-r] [-j]
# -r, --raw: Display raw command output
# -j, --json: Display output in JSON format

1.4 API Key App Developer Authorization Flow

Source: https://docs.unraid.net/API/api-key-app-developer-authorization-flow/

Applications can request API access to an Unraid server by redirecting users to a special authorization page where users can review requested permissions and create an API key with one click.

Flow

  1. Application initiates request: The app redirects the user to:

    https://[unraid-server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123

  2. User authentication: If not already logged in, the user is redirected to login first (standard Unraid auth).

  3. Consent screen: User sees:

    • Application name and description
    • Requested permissions (with checkboxes to approve/deny specific scopes)
    • API key name field (pre-filled)
    • Authorize & Cancel buttons

  4. API key creation: Upon authorization:

    • API key is created with approved scopes.
    • Key is displayed to the user.
    • If redirect_uri is provided, user is redirected back with the key.

  5. Callback: App receives the API key:

    https://myapp.com/callback?api_key=xxx&state=abc123

Query Parameters

  • name (required): Name of the requesting application
  • description (optional): Description of the application
  • scopes (required): Comma-separated list of requested scopes
  • redirect_uri (optional): URL to redirect after authorization
  • state (optional): Opaque value for maintaining state

Scope Format

Scopes follow the pattern: resource:action.

Examples:

  • docker:read -- read access to Docker
  • vm:* -- full access to VMs
  • system:update -- update access to system
  • role:viewer -- viewer role access
  • role:admin -- admin role access

Available resources: docker, vm, system, share, user, network, disk, and others. Available actions: create, read, update, delete, or * for all.

Security notes:

  • Redirect URIs must use HTTPS (except localhost for development)
  • Users explicitly approve each permission
  • The flow uses existing Unraid authentication sessions
  • API keys are shown once and must be saved securely

Example Integration (JavaScript)

const unraidServer = 'tower.local';
const appName = 'My Docker Manager';
const scopes = 'docker:*,system:read';
const redirectUri = 'https://myapp.com/unraid/callback';
const state = generateRandomState();

// Store state for verification
sessionStorage.setItem('oauth_state', state);

// Redirect user to authorization page
window.location.href =
    `https://${unraidServer}/ApiKeyAuthorize?` +
    `name=${encodeURIComponent(appName)}&` +
    `scopes=${encodeURIComponent(scopes)}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `state=${encodeURIComponent(state)}`;

// Handle callback
const urlParams = new URLSearchParams(window.location.search);
const apiKey = urlParams.get('api_key');
const returnedState = urlParams.get('state');

if (returnedState === sessionStorage.getItem('oauth_state')) {
    // Save API key securely
    saveApiKey(apiKey);
}

1.5 Programmatic API Key Management

Source: https://docs.unraid.net/API/programmatic-api-key-management/

Create, use, and delete API keys programmatically for automated workflows, CI/CD pipelines, temporary access provisioning, and infrastructure as code.

Creating API Keys

Basic creation with JSON output:

unraid-api apikey --create --name "workflow key" --roles ADMIN --json

Output:

{
    "key": "your-generated-api-key-here",
    "name": "workflow key",
    "id": "generated-uuid"
}

Advanced creation with permissions:

unraid-api apikey --create \
  --name "limited access key" \
  --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
  --description "Read-only access for monitoring" \
  --json

Handling existing keys (overwrite):

unraid-api apikey --create --name "existing key" --roles ADMIN --overwrite --json

Deleting API Keys

# Non-interactive deletion by name
unraid-api apikey --delete --name "workflow key"

# JSON output for deletion
unraid-api apikey --delete --name "workflow key" --json

Available Roles

Role Description
ADMIN Full system access
CONNECT Unraid Connect features
VIEWER Read-only access
GUEST Limited access

Available Resources

ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

Available Actions

CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN

Complete Workflow Example (Temporary Access)

#!/bin/bash
set -e

# Define cleanup function (deletes the temporary key)
cleanup() { echo "Cleaning up..."; unraid-api apikey --delete --name "temp deployment key" 2>/dev/null || true; }

# 1. Create temporary API key
echo "Creating temporary API key..."
KEY_DATA=$(unraid-api apikey --create \
  --name "temp deployment key" \
  --roles ADMIN \
  --description "Temporary key for deployment $(date)" \
  --json)

# Register trap only after key creation succeeds (nothing to clean up if creation failed)
trap cleanup EXIT

# 2. Extract the API key
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API key created successfully"

# 3. Use the key for operations
echo "Configuring services..."
curl -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "your-client-id"}' \
  http://localhost:3001/graphql

echo "Deployment completed successfully"

1.6 OIDC Provider Setup

Source: https://docs.unraid.net/API/oidc-provider-setup/

OpenID Connect (OIDC) enables Single Sign-On (SSO) for the Unraid API using external identity providers like Google, Microsoft, Authelia, Keycloak, Authentik, and Okta.

Quick Start

  1. Navigate to Settings > Management Access > API > OIDC
  2. Click the + button to add a new provider
  3. Configure the provider settings

Required Redirect URI (ALL providers)

http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback

Authorization Modes

Simple mode (recommended):

  • Allow specific email domains (e.g., @company.com)
  • Allow specific email addresses
  • Best for most users

Advanced mode:

  • Create complex authorization rules based on JWT claims
  • Operators: equals, contains, endsWith, startsWith
  • Combine conditions with OR/AND logic
  • Check group memberships, verify multiple claims

Provider-Specific Configuration

Unraid.net (built-in):

  • Pre-configured, just set authorization rules

Google:

  • Issuer URL: https://accounts.google.com
  • Requires valid domain names for OAuth redirect URIs (no local IPs or .local domains)
  • Options: Reverse Proxy, Tailscale (.ts.net), Dynamic DNS

Authelia:

  • Issuer URL: https://auth.yourdomain.com
  • Client ID: unraid-api
  • Scopes: openid, profile, email, groups

Microsoft/Azure AD:

  • Issuer URL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0

Keycloak:

  • Issuer URL: https://keycloak.example.com/realms/YOUR_REALM

Authentik:

  • Issuer URL: https://authentik.example.com/application/o/<application_slug>/

Okta:

  • Issuer URL: https://YOUR_DOMAIN.okta.com

All providers require scopes: openid, profile, email

Issuer URL Format

Use the base URL (recommended for security):

  • Base URL: https://accounts.google.com (recommended)
  • Full discovery URL: https://accounts.google.com/.well-known/openid-configuration (not recommended)

1.7 Upcoming Features / Roadmap

Source: https://docs.unraid.net/API/upcoming-features/

Completed Features

Feature Available Since
API Development Environment Improvements v4.0.0
Include API in Unraid OS Unraid v7.2-beta.1
Separate API from Connect Plugin Unraid v7.2-beta.1
Permissions System Rewrite v4.0.0
OIDC/SSO Support Unraid v7.2-beta.1
Array Status Monitoring v4.0.0
Docker Container Status Monitoring v4.0.0
Array/Cache Share Status Monitoring v4.0.0
Notifications System & Interface v4.0.0

Upcoming / In Development

Feature Target Timeline
Make API Open Source Completed - open-sourced January 2025 (GitHub)
Developer Tools for Plugins Q2 2025
User Interface Component Library In Development
New Settings Pages Q2 2025
Custom Theme Creator Q2-Q3 2025
New Connect Settings Interface Q1 2025
Storage Pool Creation/Status Interface Q2 2025
New Docker Status Interface Design Q3 2025
Docker Container Setup Interface Q3 2025
Docker Compose Support TBD
New Plugins Interface Q3 2025
Plugin Development Tools TBD

Under Consideration

  • Storage Share Creation & Settings
  • Storage Share Management Interface

Version Support

Unraid Version API Version Support Status
Unraid v7.2-beta.1+ Latest Active
7.0 - 7.1.x v4.x via Plugin Limited
6.12.x v4.x via Plugin Limited
< 6.12 Not Supported EOL

GitHub Repository

  • Open source: https://github.com/unraid/api
  • Latest release: v4.29.2 (December 19, 2025)
  • 102 releases total
  • Language: TypeScript 77.4%, Vue 11.8%, PHP 5.6%, Shell 2.3%
  • Stars: 95, Forks: 17

2. Complete GraphQL Schema

Source: https://github.com/domalab/unraid-api-client/blob/113c94f1/schema.graphql Reference: https://deepwiki.com/domalab/unraid-api-client/7-graphql-schema-reference

The Unraid GraphQL API follows standard GraphQL conventions with three root types: Query (for fetching data), Mutation (for modifying data), and Subscription (for real-time updates).

2.1 Root Types

Query Type

type Query {
    apiKeys: [ApiKey!]!
    apiKey(id: ID!): ApiKey
    array: Array!
    parityHistory: [ParityCheck]
    online: Boolean
    info: Info
    cloud: Cloud
    config: Config!
    remoteAccess: RemoteAccess!
    extraAllowedOrigins: [String!]!
    connect: Connect!
    disk(id: ID!): Disk
    disks: [Disk]!
    display: Display
    dockerContainers(all: Boolean): [DockerContainer!]!
    docker: Docker!
    dockerNetwork(id: ID!): DockerNetwork!
    dockerNetworks(all: Boolean): [DockerNetwork]!
    flash: Flash
    network: Network
    notifications: Notifications!
    owner: Owner
    registration: Registration
    server: Server
    servers: [Server!]!
    services: [Service!]!
    shares: [Share]
    unassignedDevices: [UnassignedDevice]
    me: Me
    user(id: ID!): User
    users(input: usersInput): [User!]!
    vars: Vars
    vms: Vms
}

Mutation Type

type Mutation {
    createApiKey(input: CreateApiKeyInput!): ApiKeyWithSecret!
    addPermission(input: AddPermissionInput!): Boolean!
    addRoleForUser(input: AddRoleForUserInput!): Boolean!
    addRoleForApiKey(input: AddRoleForApiKeyInput!): Boolean!
    removeRoleFromApiKey(input: RemoveRoleFromApiKeyInput!): Boolean!
    startArray: Array
    stopArray: Array
    addDiskToArray(input: arrayDiskInput): Array
    removeDiskFromArray(input: arrayDiskInput): Array
    mountArrayDisk(id: ID!): Disk
    unmountArrayDisk(id: ID!): Disk
    clearArrayDiskStatistics(id: ID!): JSON
    startParityCheck(correct: Boolean): JSON
    pauseParityCheck: JSON
    resumeParityCheck: JSON
    cancelParityCheck: JSON
    login(username: String!, password: String!): String
    shutdown: String
    reboot: String
    connectSignIn(input: ConnectSignInInput!): Boolean!
    connectSignOut: Boolean!
    enableDynamicRemoteAccess(input: EnableDynamicRemoteAccessInput!): Boolean!
    setAdditionalAllowedOrigins(input: AllowedOriginInput!): [String!]!
    setupRemoteAccess(input: SetupRemoteAccessInput!): Boolean!
    createNotification(input: NotificationData!): Notification!
    deleteNotification(id: String!, type: NotificationType!): NotificationOverview!
    deleteArchivedNotifications: NotificationOverview!
    archiveNotification(id: String!): Notification!
    unreadNotification(id: String!): Notification!
    archiveNotifications(ids: [String!]): NotificationOverview!
    unarchiveNotifications(ids: [String!]): NotificationOverview!
    archiveAll(importance: Importance): NotificationOverview!
    unarchiveAll(importance: Importance): NotificationOverview!
    recalculateOverview: NotificationOverview!
    addUser(input: addUserInput!): User
    deleteUser(input: deleteUserInput!): User
}

Note: The client schema above uses ID! for disk mutation args (e.g., mountArrayDisk(id: ID!)), but the actual server resolvers use PrefixedID!. The MCP tool code correctly uses PrefixedID! based on server source analysis.

Subscription Type

type Subscription {
    array: Array!
    parityHistory: ParityCheck!
    ping: String!
    info: Info!
    online: Boolean!
    config: Config!
    display: Display
    dockerContainer(id: ID!): DockerContainer!
    dockerContainers: [DockerContainer]
    dockerNetwork(id: ID!): DockerNetwork!
    dockerNetworks: [DockerNetwork]!
    flash: Flash!
    notificationAdded: Notification!
    notificationsOverview: NotificationOverview!
    owner: Owner!
    registration: Registration!
    server: Server
    service(name: String!): [Service!]
    share(id: ID!): Share!
    shares: [Share!]
    unassignedDevices: [UnassignedDevice!]
    me: Me
    user(id: ID!): User!
    users: [User]!
    vars: Vars!
    vms: Vms
}

2.2 Resource Types

Permission & API Key Types

type Permission {
    resource: Resource!
    actions: [String!]!
}

type ApiKey {
    id: ID!
    name: String!
    description: String
    roles: [Role!]!
    createdAt: DateTime!
    permissions: [Permission!]!
}

type ApiKeyWithSecret {
    id: ID!
    key: String!
    name: String!
    description: String
    roles: [Role!]!
    createdAt: DateTime!
    permissions: [Permission!]!
}

input CreateApiKeyInput {
    name: String!
    description: String
    roles: [Role!]
    permissions: [AddPermissionInput!]
    overwrite: Boolean
}

Array Type

type Array implements Node {
    id: ID!
    previousState: ArrayState
    pendingState: ArrayPendingState
    state: ArrayState!
    capacity: ArrayCapacity!
    boot: ArrayDisk
    parities: [ArrayDisk!]!
    disks: [ArrayDisk!]!
    caches: [ArrayDisk!]!
}

type ArrayDisk {
    id: ID!
    idx: Int!
    name: String
    device: String
    size: Long!
    status: ArrayDiskStatus
    rotational: Boolean
    temp: Int
    numReads: Long!
    numWrites: Long!
    numErrors: Long!
    fsSize: Long
    fsFree: Long
    fsUsed: Long
    exportable: Boolean
    type: ArrayDiskType!
    warning: Int
    critical: Int
    fsType: String
    comment: String
    format: String
    transport: String
}

type ArrayCapacity {
    kilobytes: Capacity!
    disks: Capacity!
}

type Capacity {
    free: String!
    used: String!
    total: String!
}

Docker Types

type DockerContainer {
    id: ID!
    names: [String!]
    image: String!
    imageId: String!
    command: String!
    created: Int!
    ports: [ContainerPort!]!
    sizeRootFs: Long
    labels: JSON
    state: ContainerState!
    status: String!
    hostConfig: ContainerHostConfig
    networkSettings: JSON
    mounts: [JSON]
    autoStart: Boolean!
}

type Docker implements Node {
    id: ID!
    containers: [DockerContainer!]
    networks: [DockerNetwork!]
}

type DockerNetwork {
    name: String
    id: ID
    created: String
    scope: String
    driver: String
    enableIPv6: Boolean!
    ipam: JSON
    internal: Boolean!
    attachable: Boolean!
    ingress: Boolean!
    configFrom: JSON
    configOnly: Boolean!
    containers: JSON
    options: JSON
    labels: JSON
}

Info (System Information) Type

type Info implements Node {
    baseboard: Baseboard
    cpu: InfoCpu
    devices: Devices
    display: Display
    id: ID!
    machineId: ID
    memory: InfoMemory
    os: Os
    system: System
    time: DateTime!
    versions: Versions
}

type InfoCpu {
    manufacturer: String!
    brand: String!
    vendor: String!
    family: String!
    model: String!
    stepping: Int!
    revision: String!
    voltage: String
    speed: Float!
    speedmin: Float!
    speedmax: Float!
    threads: Int!
    cores: Int!
    processors: Long!
    socket: String!
    cache: JSON!
    flags: [String!]
}

type InfoMemory {
    max: Long!
    total: Long!
    free: Long!
    used: Long!
    active: Long!
    available: Long!
    buffcache: Long!
    swaptotal: Long!
    swapused: Long!
    swapfree: Long!
    layout: [MemoryLayout!]
}

type Os {
    platform: String
    distro: String
    release: String
    codename: String
    arch: String
    hostname: String
    logofile: String
    serial: String
    build: String
    uptime: DateTime
}

VM Types

type Vms {
    id: ID!
    domain: [VmDomain!]
}

type VmDomain {
    uuid: ID!
    name: String
    state: VmState!
}

Network Type

type Network implements Node {
    iface: String
    ifaceName: String
    ipv4: String
    ipv6: String
    mac: String
    internal: String
    operstate: String
    type: String
    duplex: String
    mtu: String
    speed: String
    carrierChanges: String
    id: ID!
    accessUrls: [AccessUrl!]
}

Share Type

type Share {
    name: String
    free: Long
    used: Long
    size: Long
    include: [String]
    exclude: [String]
    cache: Boolean
    nameOrig: String
    comment: String
    allocator: String
    splitLevel: String
    floor: String
    cow: String
    color: String
    luksStatus: String
}

User Types

interface UserAccount {
    id: ID!
    name: String!
    description: String!
    roles: [Role!]!
    permissions: [Permission!]
}

type Me implements UserAccount {
    id: ID!
    name: String!
    description: String!
    roles: [Role!]!
    permissions: [Permission!]
}

type User implements UserAccount {
    id: ID!
    name: String!
    description: String!
    roles: [Role!]!
    password: Boolean
    permissions: [Permission!]
}

Notification Types

type Notifications implements Node {
    id: ID!
    overview: NotificationOverview!
    list(filter: NotificationFilter!): [Notification!]!
}

type Notification implements Node {
    id: ID!
    title: String!
    subject: String!
    description: String!
    importance: Importance!
    link: String
    type: NotificationType!
    timestamp: String
    formattedTimestamp: String
}

type NotificationOverview {
    unread: NotificationCounts!
    archive: NotificationCounts!
}

type NotificationCounts {
    info: Int!
    warning: Int!
    alert: Int!
    total: Int!
}

Vars Type (Server Configuration)

type Vars implements Node {
    id: ID!
    version: String          # Unraid version
    maxArraysz: Int
    maxCachesz: Int
    name: String             # Machine hostname
    timeZone: String
    comment: String
    security: String
    workgroup: String
    domain: String
    useNtp: Boolean
    ntpServer1: String
    ntpServer2: String
    ntpServer3: String
    ntpServer4: String
    useSsl: Boolean
    port: Int                # WebUI HTTP port
    portssl: Int             # WebUI HTTPS port
    useTelnet: Boolean
    useSsh: Boolean
    portssh: Int
    startPage: String
    startArray: Boolean
    spindownDelay: String
    defaultFormat: String
    defaultFsType: String
    shutdownTimeout: Int
    shareDisk: String
    shareUser: String
    shareSmbEnabled: Boolean
    shareNfsEnabled: Boolean
    shareAfpEnabled: Boolean
    shareCacheEnabled: Boolean
    shareMoverSchedule: String
    shareMoverLogging: Boolean
    safeMode: Boolean
    configValid: Boolean
    configError: ConfigErrorState
    deviceCount: Int
    flashGuid: String
    flashProduct: String
    flashVendor: String
    regState: RegistrationState
    regTo: String            # Registration owner
    mdState: String
    mdNumDisks: Int
    mdNumDisabled: Int
    mdNumInvalid: Int
    mdNumMissing: Int
    mdResync: Int
    mdResyncAction: String
    fsState: String
    fsProgress: String       # Human friendly array events string
    fsCopyPrcnt: Int         # 0-100 for disk upgrade/swap
    shareCount: Int
    shareSmbCount: Int
    shareNfsCount: Int
    csrfToken: String
    # ... and many more fields
}

Cloud/Connect Types

type Cloud {
    error: String
    apiKey: ApiKeyResponse!
    relay: RelayResponse
    minigraphql: MinigraphqlResponse!
    cloud: CloudResponse!
    allowedOrigins: [String!]!
}

type Connect implements Node {
    id: ID!
    dynamicRemoteAccess: DynamicRemoteAccessStatus!
}

type RemoteAccess {
    accessType: WAN_ACCESS_TYPE!
    forwardType: WAN_FORWARD_TYPE
    port: Port
}

Disk Type (Physical Disk)

type Disk {
    device: String!
    type: String!
    name: String!
    vendor: String!
    size: Long!
    bytesPerSector: Long!
    totalCylinders: Long!
    totalHeads: Long!
    totalSectors: Long!
    totalTracks: Long!
    tracksPerCylinder: Long!
    sectorsPerTrack: Long!
    firmwareRevision: String!
    serialNum: String!
    interfaceType: DiskInterfaceType!
    smartStatus: DiskSmartStatus!
    temperature: Long!
    partitions: [DiskPartition!]
}

2.3 Enums and Scalars

Scalar Types

Scalar Description
JSON Complex JSON data structures
Long 52-bit integers
UUID Universally Unique Identifier
DateTime RFC 3339 date-time string
Port Valid TCP port (0-65535)
URL Standard URL format

Key Enums

Resource (for permissions): api_key, array, cloud, config, connect, connect__remote_access, customizations, dashboard, disk, display, docker, flash, info, logs, me, network, notifications, online, os, owner, permission, registration, servers, services, share, vars, vms, welcome

Role: admin, connect, guest

ArrayState: STARTED, STOPPED, NEW_ARRAY, RECON_DISK, DISABLE_DISK, SWAP_DSBL, INVALID_EXPANSION, PARITY_NOT_BIGGEST, TOO_MANY_MISSING_DISKS, NEW_DISK_TOO_SMALL, NO_DATA_DISKS

ArrayDiskStatus: DISK_NP, DISK_OK, DISK_NP_MISSING, DISK_INVALID, DISK_WRONG, DISK_DSBL, DISK_NP_DSBL, DISK_DSBL_NEW, DISK_NEW

ArrayDiskType: Data, Parity, Flash, Cache

ContainerState: RUNNING, EXITED

VmState: NOSTATE, RUNNING, IDLE, PAUSED, SHUTDOWN, SHUTOFF, CRASHED, PMSUSPENDED

DiskInterfaceType: SAS, SATA, USB, PCIe, UNKNOWN

DiskFsType: xfs, btrfs, vfat, zfs

Importance (Notifications): ALERT, INFO, WARNING

NotificationType: UNREAD, ARCHIVE

WAN_ACCESS_TYPE: DYNAMIC, ALWAYS, DISABLED

RegistrationState: TRIAL, BASIC, PLUS, PRO, STARTER, UNLEASHED, LIFETIME, EEXPIRED, EGUID, EGUID1, ETRIAL, ENOKEYFILE, ENOFLASH, EBLACKLISTED, ENOCONN

3. Unraid Connect Documentation

Source: https://docs.unraid.net/unraid-connect/overview-and-setup Source: https://docs.unraid.net/unraid-connect/remote-access Source: https://docs.unraid.net/unraid-connect/automated-flash-backup

Unraid Connect is the cloud management layer that provides:

  • Remote access to your Unraid server from anywhere
  • Automated flash backup to the cloud
  • Server dashboard and monitoring from unraid.net
  • The API plugin for pre-7.2 Unraid versions

Key points:

  • Unraid Connect plugin is completely optional on 7.2+
  • The API functionality was separated from Connect in 7.2
  • You do NOT need to sign in to Unraid Connect to use the API locally
  • Connect adds cloud communication features (remote access, dashboard, flash backup)
  • Remote access uses WireGuard VPN or Dynamic DNS

4. Release Notes (API-Relevant)

Unraid 7.2.0 (October 29, 2025)

Source: https://docs.unraid.net/unraid-os/release-notes/7.2.0

Major API changes:

  • The Unraid API is now built into Unraid OS (no plugin required)
  • The new Notifications panel is the first major feature built on the API
  • Dashboard now gets CPU usage stats from the Unraid API
  • Over time, the entire webGUI will transition to use the API
  • Fully open source: https://github.com/unraid/api
  • SSO/OIDC login support for the webGUI
  • API version: dynamix.unraid.net 4.25.3

Other key 7.2.0 changes:

  • Responsive CSS (mobile-friendly webGUI)
  • ZFS RAIDZ expansion
  • Ext2/3/4, NTFS, exFAT support
  • IPv6 Docker custom networks with ULA support
  • Welcome screen for new systems

Unraid 7.1.0 (May 2025)

Source: https://docs.unraid.net/unraid-os/release-notes/7.1.0

  • API available via Unraid Connect plugin
  • Focus on ZFS improvements, Docker enhancements, and VM updates

Unraid 7.0.0 (February 2025)

Source: https://docs.unraid.net/unraid-os/release-notes/7.0.0

  • Major release introducing ZFS support
  • API available via Unraid Connect plugin
  • Modernized PHP stack and security improvements

5. Blog Posts

API Feature Bounty Program (September 5, 2025)

Source: https://unraid.net/blog/api-feature-bounty-program

Unraid launched a Feature Bounty Program for developers to contribute to the API roadmap:

  • Feature requests become bounties
  • Developers build and claim bounties for monetary rewards
  • Community-driven growth

Live bounty board: https://github.com/orgs/unraid/projects/3/views/1 Feature bounty info: https://unraid.net/feature-bounty

Community API projects highlighted:

Unraid 7.2.0 Stable Release Blog (October 29, 2025)

Source: https://unraid.net/blog/unraid-7-2-0

Highlights the API as now integrated directly into Unraid OS:

  • "The Unraid API is now integrated directly into Unraid OS, giving developers and power users new ways to interact with their systems."
  • New Notifications panel is the first major feature built on the API
  • Over time, more of the webGUI will transition to use the API
  • Fully open source at https://github.com/unraid/api
  • Supports external authentication (OIDC) for secure, scalable access

6. Community Resources

Third-Party API Client

Source: https://deepwiki.com/domalab/unraid-api-client/

The domalab/unraid-api-client repository provides:

  • Python client for the Unraid GraphQL API
  • Shell script client for bash-based automation
  • Complete GraphQL schema file (schema.graphql)
  • Example queries for all major resource types
  • Authentication examples
  • Error handling patterns

GitHub: https://github.com/domalab/unraid-api-client

Official Unraid API GitHub

Source: https://github.com/unraid/api

  • Monorepo: Unraid API / Connect / UI
  • TypeScript (77.4%), Vue (11.8%), PHP (5.6%)
  • 95 stars, 17 forks
  • 102 releases (latest v4.29.2)
  • Open source since January 2025
  • Topics: api, unraid, unraid-api, unraid-connect, unraid-ui

Community Forums

7. Source URLs Index

Official API Documentation (Primary Sources)

URL Description
https://docs.unraid.net/API/ API overview and getting started
https://docs.unraid.net/API/how-to-use-the-api/ Authentication, queries, and usage
https://docs.unraid.net/API/cli/ CLI command reference
https://docs.unraid.net/API/api-key-app-developer-authorization-flow/ App developer auth flow
https://docs.unraid.net/API/programmatic-api-key-management/ Programmatic key management
https://docs.unraid.net/API/oidc-provider-setup/ OIDC/SSO provider configuration
https://docs.unraid.net/API/upcoming-features/ Roadmap and feature status

GraphQL Schema (Primary Sources)

URL Description
https://github.com/domalab/unraid-api-client/blob/113c94f1/schema.graphql Complete GraphQL schema file
https://deepwiki.com/domalab/unraid-api-client/7-graphql-schema-reference Schema reference documentation
https://studio.apollographql.com/graph/Unraid-API/variant/current/home Apollo Studio (requires auth)

Unraid Connect Documentation

URL Description
https://docs.unraid.net/unraid-connect/overview-and-setup Connect overview
https://docs.unraid.net/unraid-connect/remote-access Remote access configuration
https://docs.unraid.net/unraid-connect/automated-flash-backup Automated flash backup

Release Notes

URL Description
https://docs.unraid.net/unraid-os/release-notes/7.2.0 Unraid 7.2.0 (API built-in)
https://docs.unraid.net/unraid-os/release-notes/7.1.0 Unraid 7.1.0
https://docs.unraid.net/unraid-os/release-notes/7.0.0 Unraid 7.0.0
https://docs.unraid.net/unraid-os/release-notes/7.0.1 Unraid 7.0.1
https://docs.unraid.net/unraid-os/release-notes/7.2.1 Unraid 7.2.1
https://docs.unraid.net/unraid-os/release-notes/7.2.2 Unraid 7.2.2
https://docs.unraid.net/unraid-os/release-notes/7.2.3 Unraid 7.2.3

Blog Posts

URL Description
https://unraid.net/blog/unraid-7-2-0 7.2.0 stable release announcement
https://unraid.net/blog/api-feature-bounty-program API Feature Bounty Program
https://unraid.net/blog/unraid-7 Unraid 7.0 announcement
https://unraid.net/blog/unraid-7-1 Unraid 7.1 announcement
https://unraid.net/blog/unraid-7-2-0-beta.1 7.2.0 beta.1
https://unraid.net/blog/unraid-7-2-0-beta.2 7.2.0 beta.2
https://unraid.net/blog/unraid-7-2-0-beta.3 7.2.0 beta.3
https://unraid.net/blog/unraid-7-2-0-rc-1 7.2.0 RC 1
https://unraid.net/blog/unraid-7-2-0-rc-2 7.2.0 RC 2

GitHub Repositories

URL Description
https://github.com/unraid/api Official Unraid API monorepo
https://github.com/unraid/api/releases API releases (102 total)
https://github.com/domalab/unraid-api-client Third-party API client (Python/Shell)
https://github.com/domalab/ha-unraid-connect Home Assistant integration
https://github.com/jmagar/unloggarr AI-powered log analysis
https://github.com/orgs/unraid/projects/3/views/1 Feature bounty board

Community

URL Description
https://forums.unraid.net/forum/93-unraid-api-unraid-connect/ API/Connect forum
https://unraid.net/feature-bounty Feature bounty program info

Data Collection Summary

  • Sites mapped: 4 (docs.unraid.net/API/, docs.unraid.net/connect/, docs.unraid.net/unraid-os/release-notes/, unraid.net/blog/)
  • Pages crawled: 7 API docs + 19 Connect + 7 release notes + 12 blog posts + 10 deepwiki pages + misc = ~60 pages
  • Vector DB chunks: 351 from docs.unraid.net, 575 from unraid.net, plus deepwiki, forums, and GitHub
  • Raw files saved: 6 files in docs/research/raw/
  • GraphQL schema: Complete schema.graphql extracted (1,600+ lines)
View Git Blame Copy Permalink