Skip to content

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.