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

⚙️ System

/api

Returns the basic status of the API server.

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

/api/system-info

Returns hardware and OS information about the host system.

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,
  "total_memory": "63931 MB",
  "used_memory": "9589 MB",
  "free_memory": "54342 MB",
  "memory_percent": 15.0,
  "is_docker": true
}

/api/version

Checks installed version against remote GitHub version.

View Response 
{
  "local": "2.1.15",
  "remote": "2.1.15",
  "is_update_available": false
}

/api/releases

Fetches the latest release notes from GitHub.

View Response 
{
  "success": true,
  "releases": [
    {
      "version": "2.1.15",
      "name": "v2.1.15",
      "published_at": "2025-11-21T11:00:57Z",
      "days_ago": 4,
      "is_prerelease": false,
      "is_draft": false,
      "html_url": "[https://github.com/fscorrupt/posterizarr/releases/tag/2.1.15](https://github.com/fscorrupt/posterizarr/releases/tag/2.1.15)",
      "body": "## What's Changed\r\n* Fix missing assets in gallery..."
    }
  ]
}

📊 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 full 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,
      "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
}

/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

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/dashboard/all

A combined endpoint used to populate the main dashboard (Status + Version + System Info).

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

Retrieves data from /api/recent-assets.

View Response 
{
  "success": true
}

/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

Submits data or triggers an action at /api/assets/upload-replacement.

View Response 
{
  "success": true
}

/api/assets/replace-from-url

Submits data or triggers an action at /api/assets/replace-from-url.

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.