Media Library Protection API¶
Paths below are backend-native; prefix them with /api through the frontend gateway. All endpoints use the normal DUMB authentication policy and are capability-gated by media_library_protection. Plex preference controls additionally require plex_library_settings.
Preflight a protected lifecycle operation
The default safe operation can be blocked when media protection requires a decision. Inspect that result before explicitly choosing another policy.
flowchart TD
Request["Plan stop, restart or update"] --> Preflight["Read media-protection preflight"]
Preflight --> Safe["Submit the lifecycle request with safe policy"]
Safe --> Decision{"Protection required?"}
Decision -->|No| Proceed["Operation may proceed"]
Decision -->|Yes| Blocked["Receive protection_required and current preflight"]
Blocked --> Review["Review activity before an explicit policy choice"]
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/process/media-protection/status |
Active/recent incidents and global recovery timing. Optional process_name. |
POST |
/process/media-protection/preflight |
Resolve affected media servers and current activity before stop, restart, update, or scheduled_update. |
GET |
/process/media-protection/policy?process_name=... |
Read a redacted per-server policy. |
PUT |
/process/media-protection/policy |
Save per-server enablement, dedicated API key, idle-stop behavior, or protected mounts. |
PUT |
/process/media-protection/settings |
Save global enablement and recovery timing. |
GET |
/process/media-protection/plex-library-settings |
Read the supported live Plex library preferences. |
PUT |
/process/media-protection/plex-library-settings |
Update only the allowlisted Plex library preferences. |
Lifecycle payloads for /stop-service, /restart-service, and /update-install accept protection_override with safe, keep_running, or stop_now. Omitting it uses safe. A blocked safe operation returns status: protection_required with the latest preflight rather than changing service state.
Dedicated Jellyfin/Emby keys are write-only. Policy responses contain an empty api_key and api_key_configured; a blank update preserves the stored key unless clear_api_key: true is supplied.