Skip to content

🚀 API Endpoints

The following API endpoints are available.

Authentication: - Option 1 (Recommended): Add ?api_key=YOUR_KEY to the URL. - Option 2: Use the X-API-Key: YOUR_KEY header. - Option 3: Use Basic Authentication (username/password). - http://admin:posterizarr@YOUR_IP:8000/api/webhook/tautulli


External Provider API

These endpoints are opt-in: they do not change regular Posterizarr runs or media-server artwork. Both require a Posterizarr API key—either in the X-API-Key header (recommended), as an Authorization: Bearer token, or as an api_key query parameter—even when Web UI authentication is disabled. Create a key in the Web UI. Basic Auth is not accepted by these endpoints.

GET /api/provider/v1/asset/{media_type}/{item_id}

GET /api/provider/v1/poster/{media_type}/{item_id} remains as a backwards- compatible alias. media_type is movie or show; the response is a JPEG. asset_type selects poster (default), background, season, or titlecard. Season and titlecard requests require season_number; titlecards also require episode_number. Seasons and titlecards require media_type=show.

provider can be auto (default), tmdb, or tvdb. With auto or tmdb, item_id is a TMDb ID; tvdb_id may additionally be supplied so the configured provider order can try TVDB. With provider=tvdb, item_id is a TVDB ID and tmdb_id may be supplied for TMDb fallback. For shows, Posterizarr attempts to resolve a missing TVDB ID through TMDb's external IDs. Artwork selection follows ProviderPriorityMode, FavProvider, ProviderOrder, and the per-media-type provider order. This API currently searches TMDb and TVDB; Fanart and Plex providers are not yet queried here.

The requested asset's Posterizarr language list is used: PreferredLanguageOrder for posters, PreferredBackgroundLanguageOrder for backgrounds, PreferredSeasonLanguageOrder for seasons, and PreferredTCLanguageOrder for titlecards. PleaseFillMe inherits the standard poster order, and TmdbLanguageMappings applies to TMDb requests. The caption uses the selected provider's localized title when available. If TVDB artwork has no matching title translation, Posterizarr uses the localized TMDb title, then TMDb's English default. A TVDB-only request without a resolvable TMDb ID can only use the TVDB title when available. TMDb is also the artwork fallback according to the configured provider order.

Posterizarr applies the corresponding manual settings from config.json (text, font, borders, and overlays) in an isolated temporary workspace. Dynamic Overlay YAML rules are not applied. The result is cached separately in database/provider_posters; the cache key includes asset type, IDs, season or episode coordinates, and relevant provider/language/render settings. Existing assets are never overwritten and no media-server upload is performed.

Pass create=false for lookup only. Without library, an existing matching asset or API cache entry may be returned, but no new asset is created. When library is provided, only an existing asset in that library is returned; the API cache is not used. Ambiguous existing matches return 409 and require library. A TMDb key is required for TMDb lookup/fallback; a TVDB key is required for TVDB. Creating an asset requires PowerShell 7 and ImageMagick. Missing artwork returns 404; rendering or upstream failures return 502 or 503.

# Existing/default poster request (same URL as before)
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/poster/movie/603" --output poster.jpg

# TVDB-first show season poster
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/asset/show/603?tvdb_id=121361&asset_type=season&season_number=2" --output season.jpg

# TMDb show season poster
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/asset/show/603?provider=tmdb&asset_type=season&season_number=2" --output season.jpg

# TVDB episode titlecard, with TMDb ID available for localized title fallback
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/asset/show/121361?provider=tvdb&tmdb_id=603&asset_type=titlecard&season_number=2&episode_number=3" --output titlecard.jpg

# TMDb episode titlecard
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/asset/show/603?provider=tmdb&asset_type=titlecard&season_number=2&episode_number=3" --output titlecard.jpg

Prefer sending the key via X-API-Key or Authorization: Bearer headers so credentials are not exposed in URLs, reverse-proxy logs, or third-party media server metadata. While ?api_key=YOUR_KEY is supported for consumers that cannot send custom headers, avoid passing API keys in shared or logged URLs.

GET /api/provider/v1/ratings/{media_type}/{item_id}

media_type is movie, show, episode, or season. This endpoint reads only existing, unexpired entries from the Dynamic Overlays ratings cache; it does not call TMDb, TVDB, MDBList, SIMKL, or OMDb and does not resolve missing IDs. With provider=auto (the default), a numeric item_id is treated as a TMDb ID and an IMDb ID beginning with tt is detected automatically. Use provider=tmdb or provider=imdb to select the cached identifier explicitly. Optional server_type selects a cache entry from plex, jellyfin, emby, or another configured media server when IDs appear in multiple caches.

Movie and show entries are matched by their cached TMDb or IMDb ID. Episodes can be matched by the series TMDb ID plus season_number and episode_number, or directly by the episode's IMDb ID. Episode coordinates are persisted during ratings refreshes. On startup, a background migration fills missing coordinates for existing Plex, Jellyfin, and Emby cache rows using only media-server metadata; it does not refresh ratings or change cache expiry. Season entries require season_number and can be found by TVDB series ID, or by TMDb/IMDb ID when a matching cached show entry and season mapping exist. Season ratings are available for anime seasons already mapped to SIMKL; the cached row may include SIMKL and MAL scores. A cache miss or expired entry returns 404.

The response title and score values come from the cached row. Each rating's source identifies the provider recorded for that score (for example, tmdb, mdblist, omdb, simkl, or imdb_dataset), and updated_at indicates the timestamp when that specific rating was refreshed or cached. New refreshes persist this per-score provenance and timestamp. For older entries, the API derives source from recorded refresh results where possible and falls back to the cache record's refresh or cached timestamp. The top-level cache object includes the cache record's server, timestamps, and record-level source. The providers object reports cached refresh statuses, not live provider status. Local IMDb dataset ratings are returned when they have already been written into the ratings cache.

# Movie or show: use an ID already present in the ratings cache
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/movie/603"
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/show/1429?provider=tmdb"

# IMDb ID lookup
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/movie/tt0133093?provider=imdb"

# Anime episode: Attack on Titan S04E30 (series TMDb ID 1429)
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/episode/1429?provider=tmdb&season_number=4&episode_number=30"

# Or request an episode directly by its cached IMDb ID
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/episode/tt27048168?provider=imdb"

# Anime season: TVDB ID and season number must match a cached season mapping
curl -H "X-API-Key: YOUR_KEY" "http://posterizarr:8000/api/provider/v1/ratings/season/12345?provider=tvdb&season_number=1"

The endpoint is not a full metadata API and does not yet support Floppy ratings. It neither refreshes nor writes cache entries. 404 means no unexpired cache entry matches the requested ID; 400 indicates an unsupported identifier or missing season number. No provider credentials are needed to read cached data.

{
  "media_type": "movie",
  "title": "The Matrix",
  "tmdb_id": 603,
  "imdb_id": "tt0133093",
  "scale": 10,
  "ratings": {
    "tmdb": {"value": 8.2, "source": "tmdb", "updated_at": "2026-11-11T12:00:00"},
    "rt_critic": {"value": 8.3, "source": "omdb", "updated_at": "2026-11-11T12:00:00"}
  },
  "providers": {"cache": "hit"},
  "cache": {
    "server_type": "plex",
    "cached_at": "2026-11-11T12:00:00",
    "expires_at": "2026-12-11T12:00:00",
    "record_source": "mdblist"
  }
}

Example season response:

{
  "media_type": "season",
  "title": "Attack on Titan S01",
  "season_number": 1,
  "scale": 10,
  "ratings": {
    "simkl": {"value": 8.4, "source": "simkl", "updated_at": "2026-11-11T12:00:00"},
    "mal": {"value": 8.6, "source": "simkl", "updated_at": "2026-11-11T12:00:00"}
  },
  "providers": {"cache": "hit"},
  "cache": {"server_type": "plex", "record_source": "simkl"}
}

Kometa does not currently have a generic HTTP ratings-provider configuration. A Kometa feature request or adapter must register the Posterizarr rating variables, authenticate, map item IDs and consume this API. Existing Kometa configurations are unaffected.


Dynamic Overlays

The /api/dynamic-overlays/episode-title-changes* endpoints power Asset Title Review across all configured text-enabled artwork types (episode, season, movie, and show).

Endpoint Purpose
GET /api/dynamic-overlays/episode-title-changes Paged review candidates. Optional search, limit, offset, status_filter (all, eligible, blocked), reason_filter (all, none, or a blocking reason), review_type (all, historical, future), and media_type_filter (all, episode, season, movie, show) filter the result set and eligible count.
POST /api/dynamic-overlays/episode-title-changes/rebuild Confirmed queue recreation; returns 409 while another run is active. candidate_ids or all_eligible with search and the same filters selects candidates. Optional force_unknown_text: true includes safe uncertain-text candidates and media-server originals (re-downloaded and EXIF-checked) in either selection.
POST /api/dynamic-overlays/episode-title-changes/queue Confirmed queueing with the same body as rebuild. Allowed while a run is active. Returns queued and queue_ids; these items start automatically once no run, queue, overlay sync, or cleanup is active.
POST /api/dynamic-overlays/episode-title-changes/dismiss Permanently hides one review entry (candidate_id) with any blocking reason.
POST /api/dynamic-overlays/episode-title-changes/fast-normal-run Confirmed Fast Normal Run over candidate_ids or all_eligible, using the same search and filters. Optional force_unknown_text: true includes safe uncertain-text candidates.

Overlay Bundles

Endpoint Purpose
GET /api/dynamic-overlays/bundle/export Download custom YAML and required custom assets/fonts plus layouts and portable settings. Official downloadable Kometa files are dependency references, not ZIP payloads. Credential fields and media-server connections are excluded; known credentials in text are masked.
POST /api/dynamic-overlays/bundle/preview Multipart file upload. Returns source profiles, existing destination libraries/server, features, file counts, conflicts, and warnings without applying the bundle.
POST /api/dynamic-overlays/bundle/import Multipart upload with file, JSON-string mapping, JSON-string anime_libraries/season_libraries, and boolean import_settings/replace_files. Applies validated mappings and starts in Dry Run, without uploading artwork.

mapping maps source profile names to existing destination library names, for example {"Source TV":"My Shows","Source Movies":""}. An empty value skips a profile. The two feature-target arrays contain mapped destination show-library names. Duplicate destinations, nonexistent libraries, and movie/show mismatches are rejected. replace_files=true explicitly approves conflicting shared files; existing files are backed up before replacement.

Local credentials and media-server selections are preserved even if an uploaded bundle contains credential fields with blank/null/masked values. Invalid bundles return 400; validation failures include detail.code and a readable detail.message so clients can translate the error. Preview responses also include warning_codes alongside the existing readable warnings list. An active sync/classification/import returns 409. See the bundle workflow and limits.

official_dependency_count in the preview reports omitted downloadable defaults. Export returns 503 with code officialCatalogUnavailable if the official Kometa catalog cannot be verified; it does not silently export the whole catalog.

POST /api/dynamic-overlays/sync

Starts a background overlay sync. Without target_items, library and target_server select the libraries and servers to scan. scope: "incremental" skips unchanged artwork; scope: "all" forces uploads.

For an item-only request, supply its media-server ID, server, and library:

{
  "target_server": "plex",
  "scope": "incremental",
  "library": "Kids Shows",
  "target_items": [
    {
      "id": "12345",
      "server_type": "plex",
      "library_name": "Kids Shows",
      "media_type": "show"
    }
  ]
}

ID targets are fetched directly, without listing unrelated libraries. Missing targets are skipped rather than falling back to a broad scan. An empty target_items list does not start a sync. Use jellyfin or emby and the corresponding item IDs for those servers.

A show target also evaluates its season posters and titlecards. Tautulli and Arr notifications submit the movie/show IDs and libraries processed by their trigger run. Requests received while a sync is running are rejected, not queued.

System Database Browser

Endpoint Purpose
GET /api/dynamic-overlays/database-stats Returns file/WAL sizes, table row counts, and status/type/category/mode breakdowns across browsable SQLite databases in database/ (overlay_cache.db, animetafill.db, imagechoices.db, runtime_stats.db, media_export.db, server_libraries.db, plex_push_cache.db, queue.db, imdb_dataset.db, and other non-excluded *.db files). config.db is strictly excluded.
GET /api/dynamic-overlays/database-entries Read-only (?mode=ro) paginated SQLite table browser with a 5-second query deadline. Accepts database (default overlay_cache.db), table (default dynamic_overlay_cache), page (>= 1, default 1), limit (1–200, default 50), search (max 300 chars), sort_by (optional column), and descending (true/false, default true). Rejects path traversal, config.db, unknown tables, and invalid sort columns with HTTP 400, and returns { "success": false, "error": "..." } on query timeout.

⚙️ System

/api

Returns the basic status of the API server.

View Response
{
  "message": "Posterizarr Web UI API",
  "status": "running"
}

/api/system-info

Returns hardware, runtime tool, and OS information about the host system. OS, CPU model, core count, Docker detection, data directory, timezone, and runtime versions (Python, PowerShell, ImageMagick) are cached for the backend process lifetime. Memory usage is collected on every request. Collection runs in worker threads so system probes do not block unrelated API requests.

View Response
{
  "platform": "Linux",
  "os_version": "Alpine Linux v3.22",
  "cpu_model": "11th Gen Intel(R) Core(TM) i5-1145G7 @ 2.60GHz",
  "cpu_cores": 8,
  "data_directory": "/config",
  "python_version": "3.12.10",
  "timezone": "UTC",
  "powershell_version": "7.4.6",
  "imagemagick_version": "ImageMagick 7.1.1-29",
  "total_memory": "63931 MB",
  "used_memory": "9589 MB",
  "free_memory": "54342 MB",
  "memory_percent": 15.0,
  "is_docker": true
}

/api/version

Checks installed version (local and raw_local) against the remote GitHub version.

View Response
{
  "local": "4.0.0",
  "raw_local": "4.0.0",
  "remote": "4.0.0",
  "is_update_available": false
}

/api/releases

Fetches the latest releases and Markdown changelogs from GitHub (TTL-cached). Pass ?refresh=true to bypass the cache and query GitHub immediately.

View Response
{
  "success": true,
  "releases": [
    {
      "version": "4.0.0",
      "name": "Posterizarr 4.0.0",
      "published_at": "2026-11-20T11:00:00Z",
      "days_ago": 0,
      "is_prerelease": false,
      "is_draft": false,
      "html_url": "https://github.com/fscorrupt/posterizarr/releases/tag/4.0.0",
      "body": "## Highlights at a Glance\r\n..."
    }
  ]
}

GET /api/whats-new

Evaluates whether the one-time post-update "What's New" modal should be shown for the currently installed stable release. Returns should_show: true only when onboarding has completed, the installed version is a published stable GitHub release (not a -dev or prerelease build), and the installed version is strictly newer than the stored last_seen_release_version.

View Response
{
  "success": true,
  "should_show": false,
  "installed_version": "4.0.0",
  "display_version": "4.0.0",
  "last_seen_version": "4.0.0",
  "release": null
}

POST /api/whats-new/dismiss

Persists the dismissed stable release version in webui_settings.json (last_seen_release_version), advancing monotonically so the post-update popup is not shown again for the same or older versions. Accepts an optional JSON body {"version": "4.0.0"} (defaults to the currently installed version).

View Response
{
  "success": true,
  "last_seen_version": "4.0.0"
}

📊 Status & Monitoring

/api/status

Returns the current execution status of the script.

View Response
{
  "running": false,
  "manual_running": false,
  "scheduler_running": false,
  "scheduler_is_executing": false,
  "last_logs": [
    "[2025-11-25 16:34:18] [INFO]    |L.33500| Finished, Total images created: 0",
    "[2025-11-25 16:34:18] [INFO]    |L.6718 |      Text-size cache: hits='0', misses='0' (0%); magick_calls='0' in '0 ms'; est_saved='0h 0m 0s'",
    "[2025-11-25 16:34:18] [INFO]    |L.33561| Script execution time: 0h 4m 14s",
    "[2025-11-25 16:34:20] [INFO]    |L.6705 | Uptime Kuma webhook sent: Status=up, Msg=OK, Ping=254627"
  ],
  "script_exists": true,
  "config_exists": true,
  "pid": null,
  "current_mode": null,
  "active_log": "Scriptlog.log",
  "already_running_detected": false,
  "running_file_exists": false,
  "start_time": null
}

/api/scheduler/status

Details regarding the internal scheduler, next run times, and active jobs.

View Response
{
  "success": true,
  "enabled": true,
  "running": true,
  "is_executing": false,
  "schedules": [
    {
      "time": "01:30",
      "description": "30min before Kometa"
    },
    {
      "time": "04:30",
      "description": "30min before Kometa"
    }
  ],
  "timezone": "Europe/Berlin",
  "last_run": "2025-11-25T16:30:00.002702",
  "next_run": "2025-11-25T19:30:00+01:00",
  "active_jobs": [
    {
      "id": "posterizarr_normal_6",
      "name": "Posterizarr Normal Mode @ 19:30",
      "next_run": "2025-11-25T19:30:00+01:00"
    }
  ]
}

/api/runtime-history

Returns a paginated history of previous script executions.

  • Query parameters: limit (1–50000, default 50), offset (>= 0, default 0), mode (optional run mode filter), and days (1–9999, optional last-N-days filter).
View Response
{
  "success": true,
  "history": [
    {
      "id": 327,
      "timestamp": "2025-11-25T16:30:03",
      "mode": "scheduled",
      "runtime_seconds": 254,
      "runtime_formatted": "0h 4m 14s",
      "total_images": 0,
      "posters": 0,
      "seasons": 0,
      "backgrounds": 0,
      "titlecards": 0,
      "collections": 0,
      "errors": 0,
      "status": "completed"
    }
  ],
  "count": 50,
  "total": 327,
  "limit": 50,
  "offset": 0,
  "mode_filter": null,
  "days": null
}

/api/runtime-history?limit=10

Returns a limited history of previous script executions.

View Response
{
  "success": true,
  "history": [
    {
      "id": 327,
      "timestamp": "2025-11-25T16:30:03",
      "mode": "scheduled",
      "runtime_seconds": 254,
      "runtime_formatted": "0h 4m 14s",
      "total_images": 0,
      "status": "completed"
    }
  ],
  "count": 10,
  "total": 327,
  "limit": 10
}

🔧 Configuration

/api/config

Returns the full configuration.

Security Note

Sensitive keys (API Tokens, Passwords, Webhooks) have been redacted in the example below.

View Response
{
  "success": true,
  "config": {
    "tvdbapi": "<REDACTED>",
    "tmdbtoken": "<REDACTED>",
    "FanartTvAPIKey": "<REDACTED>",
    "PlexToken": "<REDACTED>",
    "JellyfinAPIKey": "<REDACTED>",
    "EmbyAPIKey": "<REDACTED>",
    "FavProvider": "tmdb",
    "PreferredLanguageOrder": [
      "xx",
      "en",
      "de"
    ],
    "PlexUrl": "http://plex:32400",
    "UsePlex": "true",
    "JellyfinUrl": "http://jellyfin:8096",
    "UseJellyfin": "false",
    "EmbyUrl": "http://192.168.1.93:8096/emby",
    "UseEmby": "false",
    "SendNotification": "true",
    "AppriseUrl": "<REDACTED>",
    "UptimeKumaUrl": "<REDACTED>",
    "AssetPath": "/assets",
    "logLevel": "2",
    "basicAuthEnabled": "false",
    "basicAuthUsername": "admin",
    "basicAuthPassword": "<REDACTED>"
  },
  "ui_groups": {
    "WebUI Settings": [
      "basicAuthEnabled",
      "basicAuthUsername",
      "basicAuthPassword"
    ]
  },
  "display_names": {
    "tvdbapi": "TVDB API Key",
    "tmdbtoken": "TMDB API Token"
  },
  "tooltips": {},
  "using_flat_structure": true
}

📁 Assets & File Management

/api/assets/overview/page

Returns only the visible Action Center rows, plus category counts, type/library filter options, and the configuration used to display issue tags.

  • limit: 1-500 rows (default 25); offset: zero-based starting row (default 0).
  • tab: active (default) or skipped.
  • status: Unresolved (default), Resolved, or All.
  • category: a category key from /api/assets/overview, or empty for all categories.
  • search: case-insensitive title/root-folder search; asset_type and library: exact filters.
  • all_matches=true: return the complete filtered set for an explicitly confirmed bulk action. Normal browsing does not use this option.

total_count counts all filtered matches, not just returned rows. offset is adjusted to the last available page if necessary. Category counts and filter options remain independent of pagination. The backend still classifies the full metadata snapshot; this endpoint limits serialization and transfer, not the underlying database read. The original full overview endpoint remains available.

/api/assets/overview

Returns a categorized overview of assets (missing, non-primary language, etc.).

View Response
{
  "categories": {
    "missing_assets": {
      "count": 0,
      "assets": []
    },
    "non_primary_lang": {
      "count": 13,
      "assets": [
        {
          "id": 54766,
          "Title": "Jurassic World: Die Chaostheorie | Season 2",
          "Type": "Season",
          "Rootfolder": "Jurassic World - Chaos Theory (2024) [tvdb-440997]",
          "LibraryName": "Kids Shows",
          "Language": "en",
          "has_poster": true
        }
      ]
    },
    "resolved": {
      "count": 34,
      "assets": [
        {
          "id": 53663,
          "Title": "S01E01 | WILLKOMMEN IN PARADISE",
          "Type": "Episode",
          "LibraryName": "TV Shows",
          "Language": "Textless",
          "has_poster": true
        }
      ]
    }
  },
  "config": {
    "primary_language": "xx",
    "primary_provider": "tmdb"
  }
}

/api/assets/stats

Returns storage usage and file counts per library folder.

View Response
{
  "success": true,
  "stats": {
    "posters": 2313,
    "backgrounds": 0,
    "seasons": 2179,
    "titlecards": 34425,
    "total_size": 83481927747,
    "folders": [
      {
        "name": "Anime Shows",
        "path": "Anime Shows",
        "poster_count": 355,
        "files": 16519,
        "size": 31830640233
      },
      {
        "name": "TV Shows",
        "path": "TV Shows",
        "poster_count": 382,
        "files": 13795,
        "size": 32606586825
      }
    ]
  }
}

/api/assets-folders

Returns a specific list of asset folders and their counts.

View Response
{
  "folders": [
    {
      "name": "4K Movies",
      "path": "4K Movies",
      "files": 66,
      "size": 152763048
    },
    {
      "name": "TV Shows",
      "path": "TV Shows",
      "files": 13795,
      "size": 32606586825
    }
  ]
}

Returns a structure for the manual asset selector UI.

View Response
{
  "libraries": [
    {
      "name": "4K TV Shows",
      "folders": [
        {
          "name": "Dexter - Original Sin (2024) [tvdb-430780]",
          "path": "4K TV Shows/Dexter - Original Sin (2024) [tvdb-430780]",
          "assets": [
            {
              "name": "poster.jpg",
              "path": "4K TV Shows/Dexter - Original Sin (2024) [tvdb-430780]/poster.jpg",
              "type": "poster",
              "url": "/manual_poster_assets/4K%20TV%20Shows/Dexter%20-%20Original%20Sin%20%282024%29%20%5Btvdb-430780%5D/poster.jpg"
            }
          ],
          "asset_count": 1
        }
      ],
      "folder_count": 3
    }
  ],
  "total_assets": 226
}

/api/overlayfiles

Lists available overlay image files and fonts.

View Response
{
  "success": true,
  "files": [
    {
      "name": "Colus-Regular.ttf",
      "type": "font",
      "extension": ".ttf",
      "size": 87484
    },
    {
      "name": "overlay-innerglow.png",
      "type": "image",
      "extension": ".png",
      "size": 42936
    }
  ]
}

/api/folder-view/browse

Browses the root folder structure of assets.

View Response
{
  "success": true,
  "path": "",
  "items": [
    {
      "type": "folder",
      "name": "4K Movies",
      "path": "4K Movies",
      "item_count": 66
    },
    {
      "type": "folder",
      "name": "TV Shows",
      "path": "TV Shows",
      "item_count": 383
    }
  ]
}

🎬 Plex Export

/api/plex-export/statistics

Statistics regarding the Plex library export CSVs.

View Response
{
  "success": true,
  "statistics": {
    "total_runs": 8,
    "total_library_records": 2315,
    "total_episode_records": 2145,
    "latest_run": "2025-11-25T16:31:22.63845"
  }
}

/api/plex-export/runs

List of timestamps for previous Plex export runs.

View Response
{
  "success": true,
  "runs": [
    "2025-11-25T16:31:22.63845",
    "2025-11-22T01:31:13.933402"
  ],
  "count": 8
}

🎞️ Other Media Export

/api/other-media-export/statistics

Statistics regarding non-Plex media exports.

View Response
{
  "success": true,
  "statistics": {
    "total_runs": 0,
    "total_library_records": 0,
    "total_episode_records": 0,
    "latest_run": null
  }
}

/api/other-media-export/runs

List of timestamps for previous non-Plex export runs.

View Response
{
  "success": true,
  "runs": [],
  "count": 0
}

🖥️ Dashboard & Logs

/api/sidebar/counts

Returns only success, assets_with_issues, and manual_assets for the navigation badges, rather than full asset lists. The issue count uses the same classification as /api/assets/overview; manual totals come from the existing asset cache. Results are cached for 60 seconds per backend process, with concurrent requests sharing one calculation. ?refresh=true bypasses the cached counts after an asset replacement. Failed calculations are not cached.

View Response
{
  "success": true,
  "assets_with_issues": 12,
  "manual_assets": 7
}

/api/dashboard/all

A combined endpoint used to populate the main dashboard (Status + Version + System Info). The dashboard uses ?include_version=false to receive status, scheduler jobs, and system information without waiting for the remote version check. In this mode version is null; the frontend loads /api/version independently. The parameter defaults to true for compatibility with existing clients.

View Response
{
  "success": true,
  "status": {
    "running": false,
    "manual_running": false,
    "scheduler_running": false,
    "active_log": "Scriptlog.log"
  },
  "version": {
    "local": "2.1.15",
    "remote": "2.1.15",
    "is_update_available": false
  },
  "scheduler_status": {
    "enabled": true,
    "next_run": "2025-11-25T19:30:00+01:00"
  },
  "system_info": {
    "platform": "Linux",
    "cpu_cores": 8,
    "memory_percent": 15.0,
    "is_docker": true
  }
}

/api/logs

Lists available log files on the server.

View Response
{
  "logs": [
    {
      "name": "BackendServer.log",
      "size": 2354179,
      "directory": "UILogs"
    },
    {
      "name": "Scriptlog.log",
      "size": 27563,
      "directory": "Logs"
    }
  ]
}

🔔 Webhooks

/api/webhook/arr

Endpoint for Sonarr and Radarr On Import and On Upgrade webhooks. Converts the Arr JSON payload into a trigger file.

View Response
{
  "success": true,
  "message": "Trigger queued for Radarr",
  "file": "/config/watcher/recently_added_20251125120000_a1b2c3.posterizarr"
}

/api/webhook/tautulli

Endpoint for Tautulli notifications. Maps incoming JSON keys directly to script arguments.

View Response
{
  "success": true,
  "message": "Tautulli trigger queued",
  "file": "/config/watcher/tautulli_trigger_20251125120000_x9y8z7.posterizarr"
}

🔐 Authentication & Onboarding

/api/onboarding/complete

Submits data or triggers an action at /api/onboarding/complete.

View Response
{
  "success": true
}

/api/auth/check

Retrieves data from /api/auth/check.

View Response
{
  "success": true
}

/api/auth/keys

Retrieves data from /api/auth/keys.

View Response
{
  "success": true
}

/api/auth/keys

Submits data or triggers an action at /api/auth/keys.

View Response
{
  "success": true
}

/api/auth/keys/{key_id}

Deletes a resource at /api/auth/keys/{key_id}.

View Response
{
  "success": true
}

✅ Connection Validation

/api/validate/plex

Submits data or triggers an action at /api/validate/plex.

View Response
{
  "success": true
}

/api/validate/jellyfin

Submits data or triggers an action at /api/validate/jellyfin.

View Response
{
  "success": true
}

/api/validate/emby

Submits data or triggers an action at /api/validate/emby.

View Response
{
  "success": true
}

/api/validate/tmdb

Submits data or triggers an action at /api/validate/tmdb.

View Response
{
  "success": true
}

/api/validate/tvdb

Submits data or triggers an action at /api/validate/tvdb.

View Response
{
  "success": true
}

/api/validate/fanart

Submits data or triggers an action at /api/validate/fanart.

View Response
{
  "success": true
}

/api/validate/discord

Submits data or triggers an action at /api/validate/discord.

View Response
{
  "success": true
}

/api/validate/apprise

Submits data or triggers an action at /api/validate/apprise.

View Response
{
  "success": true
}

/api/validate/uptimekuma

Submits data or triggers an action at /api/validate/uptimekuma.

View Response
{
  "success": true
}

/api/validate/agregarr

Validates the Agregarr URL and API key against its read-only Posterizarr integration status endpoint (GET /api/v1/posterizarr/status).

(Note: Requires the bitr8/agregarr fork image bitr8/agregarr:develop with PR #103. Official/stock Agregarr releases without this PR will return HTTP 404 with a message explaining the requirement).

View Response (Success)
{
  "valid": true,
  "message": "Agregarr connection and API key are valid.",
  "details": {
    "status_code": 200
  }
}
View Response (Missing bitr8 Fork / 404)
{
  "valid": false,
  "message": "Agregarr is reachable, but its Posterizarr integration endpoint is unavailable. Requires the bitr8 Agregarr fork (Docker image bitr8/agregarr:develop) with PR #103. Upstream agregarr/agregarr does not have this endpoint.",
  "details": {
    "status_code": 404,
    "required_image": "bitr8/agregarr:develop",
    "fork_url": "https://github.com/bitr8/agregarr-dev",
    "pending_pr": "https://github.com/bitr8/agregarr-dev/pull/103"
  }
}

📚 Library & Server Management

/api/plex/action

Submits data or triggers an action at /api/plex/action.

View Response
{
  "success": true
}

/api/jellyfin-emby/action

Submits data or triggers an action at /api/jellyfin-emby/action.

View Response
{
  "success": true
}

/api/libraries/{server_type}/cached

Retrieves data from /api/libraries/{server_type}/cached.

View Response
{
  "success": true
}

/api/libraries/{server_type}/exclusions

Submits data or triggers an action at /api/libraries/{server_type}/exclusions.

View Response
{
  "success": true
}

/api/libraries/plex

Submits data or triggers an action at /api/libraries/plex.

View Response
{
  "success": true
}

/api/libraries/jellyfin

Submits data or triggers an action at /api/libraries/jellyfin.

View Response
{
  "success": true
}

/api/libraries/emby

Submits data or triggers an action at /api/libraries/emby.

View Response
{
  "success": true
}

/api/libraries/plex/items

Submits data or triggers an action at /api/libraries/plex/items.

View Response
{
  "success": true
}

▶️ Script Execution & Control

/api/run/{mode}

Submits data or triggers an action at /api/run/{mode}.

View Response
{
  "success": true
}

/api/run-manual

Submits data or triggers an action at /api/run-manual.

View Response
{
  "success": true
}

/api/run-manual-upload

Submits data or triggers an action at /api/run-manual-upload.

View Response
{
  "success": true
}

/api/run-logoupdater

Submits data or triggers an action at /api/run-logoupdater.

View Response
{
  "success": true
}

/api/run-restore

Submits data or triggers an action at /api/run-restore.

View Response
{
  "success": true
}

/api/reset-posters

Submits data or triggers an action at /api/reset-posters.

View Response
{
  "success": true
}

/api/tmdb/search-posters

Submits data or triggers an action at /api/tmdb/search-posters.

View Response
{
  "success": true
}

/api/stop

Submits data or triggers an action at /api/stop.

View Response
{
  "success": true
}

/api/force-kill

Submits data or triggers an action at /api/force-kill.

View Response
{
  "success": true
}

🖼️ Asset Galleries & Image Choices

/api/assets/skip

Adds the skip_posterizarr tag/label to the specified asset in the active media server and removes it from the Action Center.

Payload:

{
  "asset_id": 123
}

View Response
{
  "success": true,
  "message": "Successfully skipped item in Plex"
}

/api/gallery

Retrieves data from /api/gallery.

View Response
{
  "success": true
}

/api/gallery/{path:path}

Deletes a resource at /api/gallery/{path:path}.

View Response
{
  "success": true
}

/api/gallery/bulk-delete

Submits data or triggers an action at /api/gallery/bulk-delete.

View Response
{
  "success": true
}

Retrieves data from /api/backgrounds-gallery.

View Response
{
  "success": true
}

/api/backgrounds/{path:path}

Deletes a resource at /api/backgrounds/{path:path}.

View Response
{
  "success": true
}

/api/backgrounds/bulk-delete

Submits data or triggers an action at /api/backgrounds/bulk-delete.

View Response
{
  "success": true
}

Retrieves data from /api/seasons-gallery.

View Response
{
  "success": true
}

/api/seasons/{path:path}

Deletes a resource at /api/seasons/{path:path}.

View Response
{
  "success": true
}

/api/seasons/bulk-delete

Submits data or triggers an action at /api/seasons/bulk-delete.

View Response
{
  "success": true
}

Retrieves data from /api/titlecards-gallery.

View Response
{
  "success": true
}

/api/titlecards/{path:path}

Deletes a resource at /api/titlecards/{path:path}.

View Response
{
  "success": true
}

/api/titlecards/bulk-delete

Submits data or triggers an action at /api/titlecards/bulk-delete.

View Response
{
  "success": true
}

/api/manual-assets/{path:path}

Deletes a resource at /api/manual-assets/{path:path}.

View Response
{
  "success": true
}

/api/manual-assets/bulk-delete

Submits data or triggers an action at /api/manual-assets/bulk-delete.

View Response
{
  "success": true
}

Retrieves data from /api/backup-assets-gallery.

View Response
{
  "success": true
}

/api/backup-assets/{path:path}

Deletes a resource at /api/backup-assets/{path:path}.

View Response
{
  "success": true
}

/api/backup-assets/bulk-delete

Submits data or triggers an action at /api/backup-assets/bulk-delete.

View Response
{
  "success": true
}

/api/thumbnail

Retrieves data from /api/thumbnail.

View Response
{
  "success": true
}

/api/assets-folder-images/{image_type}/{folder_path:path}

Retrieves data from /api/assets-folder-images/{image_type}/{folder_path:path}.

View Response
{
  "success": true
}

/api/recent-assets

Returns recently modified assets with existing artwork. The dashboard requests only its visible page using limit (1-100, default 100), offset (default 0), and tab (All, Posters, Collections, Backgrounds, Seasons, or TitleCards). The latest 100 matching records are deduplicated before tab filtering and pagination. total_count is the selected tab's count; counts contains counts for all tabs. An offset beyond the available entries is adjusted to the last page. Asset metadata is still matched against the in-memory file cache to preserve modification-time ordering; pagination limits the response, not the database scan.

View Response
{
  "success": true,
  "assets": [],
  "total_count": 0,
  "offset": 0,
  "counts": {
    "All": 0,
    "Posters": 0,
    "Collections": 0,
    "Backgrounds": 0,
    "Seasons": 0,
    "TitleCards": 0
  }
}

/api/asset-type-lookup

Retrieves data from /api/asset-type-lookup.

View Response
{
  "success": true
}

Retrieves data from /api/test-gallery.

View Response
{
  "success": true
}

/api/imagechoices

Retrieves data from /api/imagechoices.

View Response
{
  "success": true
}

/api/imagechoices

Submits data or triggers an action at /api/imagechoices.

View Response
{
  "success": true
}

/api/imagechoices/{title}

Retrieves data from /api/imagechoices/{title}.

View Response
{
  "success": true
}

/api/imagechoices/{record_id}

Updates a resource at /api/imagechoices/{record_id}.

View Response
{
  "success": true
}

/api/imagechoices/{record_id}

Deletes a resource at /api/imagechoices/{record_id}.

View Response
{
  "success": true
}

/api/imagechoices/{record_id}/find-asset

Retrieves data from /api/imagechoices/{record_id}/find-asset.

View Response
{
  "success": true
}

/api/imagechoices/import

Submits data or triggers an action at /api/imagechoices/import.

View Response
{
  "success": true
}

🔄 Assets Replacement & Operations

/api/assets/fetch-replacements

Submits data or triggers an action at /api/assets/fetch-replacements.

View Response
{
  "success": true
}

/api/assets/upload-replacement

Uploads a replacement image. With add_to_queue=true the item is queued instead of processed immediately; adding start_when_idle=true starts it automatically once no run is active.

View Response
{
  "success": true
}

/api/assets/replace-from-url

Replaces an asset from a provider URL. Supports the same add_to_queue and start_when_idle query parameters as upload-replacement.

View Response
{
  "success": true
}

/api/assets/delete-asset/{record_id}

Deletes a resource at /api/assets/delete-asset/{record_id}.

View Response
{
  "success": true
}

/api/assets/bulk-delete-assets

Submits data or triggers an action at /api/assets/bulk-delete-assets.

View Response
{
  "success": true
}

/api/refresh-cache

Submits data or triggers an action at /api/refresh-cache.

View Response
{
  "success": true
}

/api/cache/status

Retrieves data from /api/cache/status.

View Response
{
  "success": true
}

⏰ Scheduler & Queue Management

/api/scheduler/config

Retrieves data from /api/scheduler/config.

View Response
{
  "success": true
}

/api/scheduler/config

Submits data or triggers an action at /api/scheduler/config.

View Response
{
  "success": true
}

/api/scheduler/schedule

Submits data or triggers an action at /api/scheduler/schedule.

View Response
{
  "success": true
}

/api/scheduler/schedule/{time}

Deletes a resource at /api/scheduler/schedule/{time}.

View Response
{
  "success": true
}

/api/scheduler/schedules

Deletes a resource at /api/scheduler/schedules.

View Response
{
  "success": true
}

/api/scheduler/enable

Submits data or triggers an action at /api/scheduler/enable.

View Response
{
  "success": true
}

/api/scheduler/disable

Submits data or triggers an action at /api/scheduler/disable.

View Response
{
  "success": true
}

/api/scheduler/restart

Submits data or triggers an action at /api/scheduler/restart.

View Response
{
  "success": true
}

/api/scheduler/run-now

Submits data or triggers an action at /api/scheduler/run-now.

View Response
{
  "success": true
}

/api/queue

Retrieves data from /api/queue.

View Response
{
  "success": true
}

/api/queue/{item_id}

Deletes a resource at /api/queue/{item_id}.

View Response
{
  "success": true
}

/api/queue/clear

Submits data or triggers an action at /api/queue/clear.

View Response
{
  "success": true
}

/api/queue/run

Submits data or triggers an action at /api/queue/run.

View Response
{
  "success": true
}

/api/queue/delete

Submits data or triggers an action at /api/queue/delete.

View Response
{
  "success": true
}

🔤 Fonts & Overlay Creator

/api/overlayfiles/upload

Submits data or triggers an action at /api/overlayfiles/upload.

View Response
{
  "success": true
}

/api/overlayfiles/{filename}

Deletes a resource at /api/overlayfiles/{filename}.

View Response
{
  "success": true
}

/api/overlayfiles/preview/{filename}

Retrieves data from /api/overlayfiles/preview/{filename}.

View Response
{
  "success": true
}

/api/fonts

Retrieves data from /api/fonts.

View Response
{
  "success": true
}

/api/fonts/upload

Submits data or triggers an action at /api/fonts/upload.

View Response
{
  "success": true
}

/api/fonts/{filename}

Deletes a resource at /api/fonts/{filename}.

View Response
{
  "success": true
}

/api/fonts/download/{filename}

Retrieves data from /api/fonts/download/{filename}.

View Response
{
  "success": true
}

/api/fonts/preview/{filename}

Retrieves data from /api/fonts/preview/{filename}.

View Response
{
  "success": true
}

/api/overlay-creator/preview

Submits data or triggers an action at /api/overlay-creator/preview.

View Response
{
  "success": true
}

/api/overlay-creator/save

Submits data or triggers an action at /api/overlay-creator/save.

View Response
{
  "success": true
}

📈 Runtime History & Exports Additional

/api/runtime-stats

Retrieves data from /api/runtime-stats.

View Response
{
  "success": true
}

/api/runtime-summary

Retrieves data from /api/runtime-summary.

View Response
{
  "success": true
}

/api/runtime-history/cleanup

Deletes a resource at /api/runtime-history/cleanup.

View Response
{
  "success": true
}

/api/runtime-history/migrate

Submits data or triggers an action at /api/runtime-history/migrate.

View Response
{
  "success": true
}

/api/runtime-history/migration-status

Retrieves data from /api/runtime-history/migration-status.

View Response
{
  "success": true
}

/api/runtime-history/migrate-format

Submits data or triggers an action at /api/runtime-history/migrate-format.

View Response
{
  "success": true
}

/api/runtime-history/import-json

Submits data or triggers an action at /api/runtime-history/import-json.

View Response
{
  "success": true
}

/api/plex-export/library

Retrieves data from /api/plex-export/library.

View Response
{
  "success": true
}

/api/plex-export/episodes

Retrieves data from /api/plex-export/episodes.

View Response
{
  "success": true
}

/api/plex-export/import

Submits data or triggers an action at /api/plex-export/import.

View Response
{
  "success": true
}

/api/other-media-export/library

Retrieves data from /api/other-media-export/library.

View Response
{
  "success": true
}

/api/other-media-export/episodes

Retrieves data from /api/other-media-export/episodes.

View Response
{
  "success": true
}

/api/other-media-export/import

Submits data or triggers an action at /api/other-media-export/import.

View Response
{
  "success": true
}

🗄️ Additional Configuration & Database

/api/config/backup

Submits data or triggers an action at /api/config/backup.

View Response
{
  "success": true
}

/api/config/export

Retrieves data from /api/config/export.

View Response
{
  "success": true
}

/api/config/import

Submits data or triggers an action at /api/config/import.

View Response
{
  "success": true
}

/api/custom-blueprints

Retrieves data from /api/custom-blueprints.

View Response
{
  "success": true
}

/api/custom-blueprints

Submits data or triggers an action at /api/custom-blueprints.

View Response
{
  "success": true
}

/api/config-db/status

Retrieves data from /api/config-db/status.

View Response
{
  "success": true
}

/api/config-db/section/{section}

Retrieves data from /api/config-db/section/{section}.

View Response
{
  "success": true
}

/api/config-db/value/{section}/{key}

Retrieves data from /api/config-db/value/{section}/{key}.

View Response
{
  "success": true
}

/api/config-db/sync

Submits data or triggers an action at /api/config-db/sync.

View Response
{
  "success": true
}

/api/config-db/export

Retrieves data from /api/config-db/export.

View Response
{
  "success": true
}

/api/webui-settings

Retrieves data from /api/webui-settings.

View Response
{
  "success": true
}

/api/webui-settings

Submits data or triggers an action at /api/webui-settings.

View Response
{
  "success": true
}

📋 Logs, Diagnostics & Misc

/api/logs/ui

Submits data or triggers an action at /api/logs/ui.

View Response
{
  "success": true
}

/api/logs/ui/batch

Submits data or triggers an action at /api/logs/ui/batch.

View Response
{
  "success": true
}

/api/logs/{log_name}

Retrieves data from /api/logs/{log_name}.

View Response
{
  "success": true
}

/api/logs/{log_name}/exists

Retrieves data from /api/logs/{log_name}/exists.

View Response
{
  "success": true
}

/api/logs/ui/unified

Retrieves data from /api/logs/ui/unified.

View Response
{
  "success": true
}

/api/upload-diagnostics

Retrieves data from /api/upload-diagnostics.

View Response
{
  "success": true
}

/api/admin/support-zip

Submits data or triggers an action at /api/admin/support-zip.

View Response
{
  "success": true
}

/api/logs-watcher/status

Retrieves data from /api/logs-watcher/status.

View Response
{
  "success": true
}

/api/analytics/providers

Retrieves data from /api/analytics/providers.

View Response
{
  "success": true
}

/api/running-file

Deletes a resource at /api/running-file.

View Response
{
  "success": true
}

/api/version-ui

Retrieves data from /api/version-ui.

View Response
{
  "success": true
}

🎨 Creator Mode & Collections

GET /api/collections/presets

Get collection presets from the configuration database.

View Response
[
  {
    "id": "1234567890",
    "name": "My Custom Blue Preset",
    "bgType": "texture",
    "overlayImage": "data:image/png;base64,..."
  }
]

POST /api/collections/presets

Save collection presets to the configuration database.

POST /api/collections/save

Save the generated collection poster locally in the Assets directory.

POST /api/collections/upload-to-server

Upload a poster directly to the connected Media Server (Plex, Jellyfin, Emby).

POST /api/media-server/collections

Fetch collections directly from the configured media server. When querying Plex, collections are automatically enriched with local asset diff tracking (syncStatus: synced, update_available, missing_server, missing_local), local image URLs (local_asset_url), and disk paths (local_asset_path).

POST /api/plex/collections/push-item

Uploads a single local collection poster directly to Plex via PMS REST API and updates the local push cache database (database/plex_push_cache.db).

View Request
{
  "rating_key": "12345",
  "local_path": "/assets/Collections/Star Wars Collection.png",
  "url": "http://192.168.1.50:32400",
  "token": "plex-token",
  "title": "Star Wars Collection"
}
View Response
{
  "success": true,
  "message": "Pushed poster for 'Star Wars Collection' to Plex",
  "rating_key": "12345",
  "status": "synced"
}

POST /api/plex/collections/push-batch

Concurrently uploads multiple out-of-sync collection posters to Plex. Uses a controlled concurrency semaphore to prevent overwhelming the Plex Media Server.

View Request
{
  "items": [
    {
      "rating_key": "12345",
      "local_path": "/assets/Collections/Star Wars Collection.png",
      "title": "Star Wars Collection"
    }
  ],
  "url": "http://192.168.1.50:32400",
  "token": "plex-token"
}
View Response
{
  "success": true,
  "total": 1,
  "pushed": 1,
  "failed": 0,
  "results": [
    {
      "rating_key": "12345",
      "title": "Star Wars Collection",
      "status": "synced"
    }
  ]
}

POST /api/plex/sync/run

Triggers an on-demand, lightweight background Plex artwork sync in Python (without invoking PowerShell). Scans for modified or missing assets according to specified library and asset types, pushes them to Plex, and writes execution logs to UILogs/PlexSync.log.

View Request
{
  "library": "all",
  "asset_types": ["collection", "poster", "season", "titlecard", "background"]
}
View Response
{
  "success": true,
  "message": "Plex sync started in background",
  "library": "all",
  "asset_types": ["collection", "poster", "season", "titlecard", "background"]
}

GET /api/studio-logos

Get the list of available studio logos from the GitHub repository, caching them locally.

GET /api/studio-logos/image/{filename}

Serve a specific studio logo image from the local cache.

POST /api/collections/search

Search TMDB for collections by name or ID (e.g. tmdb:12345).

POST /api/media/logos

Search TMDB for media (movies or TV shows) and retrieve their logos.

GET /api/proxy-image

Proxy external images (like TMDB/Fanart) to avoid CORS issues on the frontend canvas.

GET /api/assets/folders

Get folders from the assets directory. If library_name is provided, returns all media folders within that library; otherwise returns all top-level library directories.

View Response
{
  "success": true,
  "folders": [
    {
      "folderName": "Inception (2010) {tmdb-27205}",
      "title": "Inception",
      "year": "2010",
      "path": "Movies/Inception (2010) {tmdb-27205}"
    }
  ],
  "library": "Movies"
}

GET /api/assets/skipped

Retrieve all skipped items detected during runs, including item title, library, skip reason, and resolution status.

POST /api/assets/skipped/refresh

Forces a re-scan of log files to refresh and update the list of skipped assets.

POST /api/assets/unskip

Marks a skipped item as unskipped or resolved so it can be reprocessed on the next run.

GET /api/proxy/poster

Proxies local or remote poster images to provide secure previews and avoid CORS restrictions.

POST /api/media-server/items

Fetch paginated items from a connected media server (Plex, Jellyfin, Emby) with clearLogo presence detection and proxied image URLs.

View Request
{
  "server_type": "plex",
  "url": "http://192.168.1.50:32400",
  "token": "plex-token-here",
  "library_id": "1",
  "start": 0,
  "limit": 50
}

POST /api/media-server/check-logos

Batch checks a list of item IDs (rating_keys) against Plex to verify which items already have clearLogo artwork.

GET /api/media-server/image

Securely proxies image streams directly from Plex, Jellyfin, or Emby servers without exposing authentication tokens in frontend image URLs. Features persistent local disk caching (Cache/server_thumbs/) and public HTTP cache headers (Cache-Control: public, max-age=604800) to eliminate redundant server polling and optimize UI load speeds.

Downloads a selected logo (from URL or data URI), applies Posterizarr metadata tags using Pillow/ImageMagick, and uploads it directly to the media server as a clearLogo.


🖼️ Media Server Collections & Artwork Push

POST /api/media-server/collections

Fetches collections from the media server with diff status detection (Plex) comparing local collection assets against server artwork. Returns syncStatus (synced, update_available, missing_server, missing_local), localPosterUrl, and server poster URLs.

POST /api/plex/collections/mark-synced

Marks a local collection poster as In-Sync with Plex in the persistent SQLite cache (database/plex_push_cache.db) without performing a re-upload, updating the status badge immediately.

POST /api/plex/collections/push-item

Pushes a local collection poster or backdrop directly to Plex Media Server via REST API (/library/metadata/{rating_key}/posters or /arts) and records the updated timestamp and size in the cache.

POST /api/plex/collections/push-batch

Batches multiple collection poster pushes to Plex with rate limiting and concurrency management.

POST /api/plex/sync/run

Triggers an on-demand background Plex Push Sync job across configured libraries and asset types.


🔌 WebSockets

GET /ws/events

Status probe endpoint for the real-time WebSocket event stream. Used by the Jellyfin and Emby plugin configuration pages to verify network reachability and validate the API key before establishing a persistent WebSocket connection.

Authentication: - Requires X-API-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY HTTP header.

View Response
{
  "status": "online",
  "websocket": true,
  "endpoint": "/ws/events",
  "version": "2.0",
  "authenticated": true
}

WebSocket /ws/events

Real-time event bridge for media server integration plugins (Jellyfin and Emby). Dispatches instantaneous notifications whenever artwork is created, uploaded, replaced, or processed with overlays (both from background script runs and manual WebUI operations).

Authentication: - Strictly via X-API-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY HTTP headers during the WebSocket upgrade handshake (API keys in URL query parameters are rejected).

Supported Events: - connected: Sent upon successful handshake connection. - ping: Sent periodically to keep connections alive (client replies with pong). - asset_updated: Dispatched when an asset is modified, newly created, or overlay processing completes.

View Event Payload (asset_updated)
{
  "event": "asset_updated",
  "library_name": "Movies",
  "folder_name": "Inception (2010) [tmdb-27205]",
  "asset_type": "poster",
  "season_number": null,
  "episode_number": null,
  "title": "Inception",
  "relative_path": "Movies/Inception (2010) [tmdb-27205]/poster.jpg",
  "timestamp": "2026-09-10T07:12:00Z",
  "libraryName": "Movies",
  "folderName": "Inception (2010) [tmdb-27205]",
  "assetType": "poster",
  "seasonNumber": null,
  "episodeNumber": null,
  "relativePath": "Movies/Inception (2010) [tmdb-27205]/poster.jpg"
}

POST /api/internal/asset-event

Internal event ingestion endpoint for triggering real-time asset updates to connected media servers.

Authentication: - Bypassed for loopback connections (127.0.0.1, ::1) or requires standard API key authentication.

View Request Body
{
  "library_name": "Movies",
  "folder_name": "Gladiator II (2024)",
  "asset_type": "poster",
  "relative_path": "Movies/Gladiator II (2024)/poster.jpg",
  "title": "Gladiator II"
}

WebSocket /ws/logs

Streams live execution logs line-by-line directly to the Web UI terminal viewer (LogViewer.jsx).

WebSocket /ws/status

Broadcasts live system metrics, background execution states, and queue progress to the UI.