---
title: Using the Unraid API
description: Learn how to interact with your Unraid server through the GraphQL API
sidebar_position: 2
---

# Using the Unraid API

:::tip[Quick Start]
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)

:::info[Preferred Method]
Using the Web GUI is the easiest way to enable the GraphQL sandbox.
:::

1. Navigate to **Settings** → **Management Access** → **Developer Options**
2. Enable the **GraphQL Sandbox** toggle
3. Access the GraphQL playground by navigating to:

    ```txt
    http://YOUR_SERVER_IP/graphql
    ```

### CLI Method

Alternatively, you can enable developer mode using the CLI:

```bash
unraid-api developer --sandbox true
```

Or use the interactive mode:

```bash
unraid-api developer
```

## 🔑 Authentication

:::warning[Required for Most Operations]
Most queries and mutations require authentication. Always include appropriate credentials in your requests.
:::

You can authenticate using:

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

### Managing API Keys

<tabs>
<tabItem value="gui" label="Web GUI (Recommended)" default>

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

</tabItem>
<tabItem value="cli" label="CLI Method">

You can also use the CLI to create an API key:

```bash
unraid-api apikey --create
```

Follow the prompts to set:

- Name
- Description
- Roles
- Permissions

</tabItem>
</tabs>

### Using API Keys

The generated API key should be included in your GraphQL requests as a header:

```json
{
    "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

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

#### Monitor Array Status

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

#### List Docker Containers

```graphql
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 Identification](https://graphql.org/learn/global-object-identification/)
- `JSON`: For complex JSON data
- `DateTime`: For timestamp values
- `Long`: For 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

### Role-Based Access

Available roles:

- `admin`: Full access
- `connect`: Remote access features
- `guest`: Limited read access

## ✨ Best Practices

:::tip[Pro Tips]
1. Use the Apollo Sandbox to explore the schema and test queries
2. Start with small queries and gradually add fields as needed
3. Monitor your query complexity to maintain performance
4. Use appropriate roles and permissions for your API keys
5. Keep your API keys secure and rotate them periodically
:::

## ⏱️ Rate Limiting

:::caution[Rate Limits]
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:

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

## 📚 Additional Resources

:::info[Learn More]
- 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](/cli) or run `unraid-api --help`.
:::
