api

API Reference

Overview

Muximux provides a REST API for managing configuration, apps, groups, health, authentication, icons, and themes. All endpoints return JSON.

When authentication is enabled, most endpoints require a valid session cookie or API key (X-Api-Key header). Write operations (POST, PUT, DELETE) require the admin role.

---

Authentication

Endpoint	Method	Auth Required	Description
/api/auth/login	POST	No	Login with username/password
/api/auth/logout	POST	No	Logout (clears session)
/api/auth/status	GET	No	Check auth status and current user
/api/auth/me	GET	Yes	Get current user details
/api/auth/password	POST	Yes	Change password (builtin auth only)
/api/auth/users	GET	Admin	List all users
/api/auth/users	POST	Admin	Create a new user
/api/auth/users/{username}	PUT	Admin	Update user role/email/display name
/api/auth/users/{username}	DELETE	Admin	Delete a user
/api/auth/method	PUT	Admin	Switch authentication method
/api/auth/oidc/login	GET	No	Redirect to OIDC provider
/api/auth/oidc/callback	GET	No	OIDC callback handler

Login request:

POST /api/auth/login
{
  "username": "admin",
  "password": "secretpassword"
}

Login response:

{
  "success": true,
  "user": {
    "username": "admin",
    "role": "admin",
    "email": "admin@example.com",
    "display_name": "Admin User"
  }
}

API key authentication:

Instead of a session cookie, you can authenticate with an API key by including the X-Api-Key header:

GET /api/apps
X-Api-Key: your-api-key-here

The API key is configured in auth.api_key in your config file.

User Management

List users:

GET /api/auth/users

Returns an array of users (without password hashes):

[
  {"username": "admin", "role": "admin", "email": "admin@example.com", "display_name": "Admin User"},
  {"username": "viewer", "role": "user", "email": "", "display_name": ""}
]

Create user:

POST /api/auth/users
{
  "username": "newuser",
  "password": "minimum8chars",
  "role": "user",
  "email": "user@example.com",
  "display_name": "New User"
}

Validation: username is required, password must be at least 8 characters. Valid roles: admin, user, guest. If the role is omitted or invalid, it defaults to user.

Update user:

PUT /api/auth/users/newuser
{
  "role": "admin",
  "email": "updated@example.com",
  "display_name": "Updated Name"
}

All fields are optional -- only provided fields are updated.

Delete user:

DELETE /api/auth/users/newuser

Constraints: you cannot delete your own account, and you cannot delete the last admin user.

Auth Method Switching

Switch authentication method:

PUT /api/auth/method
{
  "method": "forward_auth",
  "trusted_proxies": ["10.0.0.0/8"],
  "headers": {
    "user": "Remote-User",
    "email": "Remote-Email",
    "groups": "Remote-Groups",
    "name": "Remote-Name"
  }
}

Valid methods: builtin, forward_auth, none. Switching to builtin requires at least one user to exist. Switching to forward_auth requires trusted_proxies. The change takes effect immediately without a restart.

---

Configuration

Endpoint	Method	Role	Description
/api/config	GET	Any	Get full configuration
/api/config	PUT	Admin	Update full configuration

The PUT endpoint accepts the full configuration object. Changes to most settings take effect immediately. Server-level settings (listen address, TLS, gateway) require a restart. Auth method changes can be made live via PUT /api/auth/method.

---

Apps

Endpoint	Method	Role	Description
/api/apps	GET	Any	List all apps
/api/apps	POST	Admin	Create a new app
/api/app/{name}	GET	Any	Get app by name
/api/app/{name}	PUT	Admin	Update app
/api/app/{name}	DELETE	Admin	Delete app

Create app request:

POST /api/apps
{
  "name": "Sonarr",
  "url": "http://sonarr:8989",
  "icon": {
    "type": "dashboard",
    "name": "sonarr"
  },
  "group": "Media",
  "enabled": true,
  "open_mode": "iframe"
}

---

Groups

Endpoint	Method	Role	Description
/api/groups	GET	Any	List all groups
/api/groups	POST	Admin	Create a new group
/api/group/{name}	GET	Any	Get group by name
/api/group/{name}	PUT	Admin	Update group
/api/group/{name}	DELETE	Admin	Delete group

---

Health

Endpoint	Method	Description
/api/health	GET	Simple health probe (for load balancers)
/api/apps/health	GET	Get health status for all apps
/api/apps/{name}/health	GET	Get health status for one app
/api/apps/{name}/health/check	POST	Trigger immediate health check

The /api/health endpoint always returns 200 OK when the server is running. It is intended for use with load balancers and uptime monitors.

Health status response:

{
  "name": "Sonarr",
  "status": "healthy",
  "response_time_ms": 42,
  "last_check": "2024-01-15T10:30:00Z",
  "uptime_percent": 99.8,
  "check_count": 1440,
  "success_count": 1437
}

Status values:

• healthy -- Last check received an HTTP 2xx response
• unhealthy -- Last check failed (error, timeout, or non-2xx response)
• unknown -- App has not been checked yet

---

Icons

Endpoint	Method	Role	Description
/api/icons/dashboard	GET	Any	List dashboard icons
/api/icons/dashboard/{name}	GET	Any	Get dashboard icon metadata
/api/icons/lucide	GET	Any	List Lucide icons
/api/icons/lucide/{name}	GET	Any	Get Lucide icon SVG
/api/icons/custom	GET	Any	List custom icons
/api/icons/custom	POST	Admin	Upload custom icon (multipart, 5MB limit)
/api/icons/custom/{name}	DELETE	Admin	Delete custom icon

Upload custom icon:

Send a multipart form request with the icon file:

POST /api/icons/custom
Content-Type: multipart/form-data

file: (binary data)

Accepted formats: PNG, SVG, JPG, WebP. Maximum file size: 5MB.

---

Themes

Endpoint	Method	Role	Description
/api/themes	GET	Any	List all themes
/api/themes	POST	Admin	Save custom theme
/api/themes/{name}	DELETE	Admin	Delete custom theme

---

Proxy Status

Endpoint	Method	Description
/api/proxy/status	GET	Get Caddy proxy status

Response:

{
  "enabled": true,
  "running": true,
  "tls": true,
  "domain": "muximux.example.com"
}

---

WebSocket

Endpoint	Protocol	Description
/ws	WebSocket	Real-time event stream

Connect to /ws to receive real-time updates. Events are sent as JSON messages:

{"type": "config_updated", "payload": {...}}
{"type": "health_changed", "payload": [...]}
{"type": "app_health_changed", "payload": {"app": "Sonarr", "health": {"status": "healthy", ...}}}

Event types:

Type	Payload	Description
config_updated	Full config object	Configuration was changed (via Settings panel or API)
health_changed	Array of health statuses	Health status changed for one or more apps
app_health_changed	{"app": "name", "health": {...}}	Health status changed for a specific app

The WebSocket client automatically reconnects if the connection drops, using exponential backoff (up to 30 seconds between retries, max 10 attempts).

---

Rate Limiting

The login endpoint (POST /api/auth/login) is rate-limited to 5 attempts per IP address per minute to prevent brute-force attacks. If the limit is exceeded, the endpoint returns HTTP 429 (Too Many Requests).

Other API endpoints are not rate-limited.