Using the Unraid API
The Unraid API provides a powerful GraphQL interface for managing your server. This guide covers authentication, common queries, and best practices.
The Unraid API provides a GraphQL interface that allows you to interact with your Unraid server. This guide will help you get started with exploring and using the API.
🎮 Enabling the GraphQL Sandbox
Web GUI Method (Recommended)
Using the Web GUI is the easiest way to enable the GraphQL sandbox.
-
Navigate to Settings → Management Access → Developer Options
-
Enable the GraphQL Sandbox toggle
-
Access the GraphQL playground by navigating to:
http://YOUR_SERVER_IP/graphql
CLI Method
Alternatively, you can enable developer mode using the CLI:
unraid-api developer --sandbox true
Or use the interactive mode:
unraid-api developer
🔑 Authentication
Most queries and mutations require authentication. Always include appropriate credentials in your requests.
You can authenticate using:
- API Keys - For programmatic access
- Cookies - Automatic when signed into the WebGUI
- SSO/OIDC - When configured with external providers
Managing API Keys
Navigate to Settings → Management Access → API Keys in your Unraid web interface to:
- View existing API keys
- Create new API keys
- Manage permissions and roles
- Revoke or regenerate keys
You can also use the CLI to create an API key:
unraid-api apikey --create
Follow the prompts to set:
- Name
- Description
- Roles
- Permissions
Using API Keys
The generated API key should be included in your GraphQL requests as a header:
{
"x-api-key": "YOUR_API_KEY"
}
📊 Available Schemas
The API provides access to various aspects of your Unraid server:
System Information
- Query system details including CPU, memory, and OS information
- Monitor system status and health
- Access baseboard and hardware information
Array Management
- Query array status and configuration
- Manage array operations (start/stop)
- Monitor disk status and health
- Perform parity checks
Docker Management
- List and manage Docker containers
- Monitor container status
- Manage Docker networks
Remote Access
- Configure and manage remote access settings
- Handle SSO configuration
- Manage 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
The API includes several core types:
Base Types
Node
: Interface for objects with unique IDs - please see Object IdentificationJSON
: For complex JSON dataDateTime
: For timestamp valuesLong
: For 64-bit integers
Resource Types
Array
: Array and disk managementDocker
: Container and network managementInfo
: System informationConfig
: Server configurationConnect
: Remote access settings
Role-Based Access
Available roles:
admin
: Full accessconnect
: Remote access featuresguest
: Limited read access
✨ Best Practices
- Use the Apollo Sandbox to explore the schema and test queries
- Start with small queries and gradually add fields as needed
- Monitor your query complexity to maintain performance
- Use appropriate roles and permissions for your API keys
- Keep your API keys secure and rotate them periodically
⏱️ Rate Limiting
The API implements rate limiting to prevent abuse. Ensure your applications handle rate limit responses appropriately.
🚨 Error Handling
The API returns standard GraphQL errors in the following format:
{
"errors": [
{
"message": "Error description",
"locations": [...],
"path": [...]
}
]
}
📚 Additional Resources
- Use the Apollo Sandbox's schema explorer to browse all available types and fields
- Check the documentation tab in Apollo Sandbox for detailed field descriptions
- Monitor the API's health using
unraid-api status
- Generate reports using
unraid-api report
for troubleshooting
For more information about specific commands and configuration options, refer to the CLI documentation or run unraid-api --help
.