API content and imports

Scan a folder and add supported files: {"folder": "/absolute/path", "chosen_emulators": {"Platform": "app_id"}}. Supported extensions include .sh, .appimage, .exe, .iso, .rom, console ROMs (.nes, .sfc, .smc, .gba, .gb, .gbc), and archives (.zip, .7z, .rar) plus .m3u, .cue, .chd, .wbfs, .rvz, .n64, .z64, .v64, .nds, .3ds, .cia, .pbp, .vpk, .xci, .nsp, .wad, .ciso, .gcm, .gcz, .wia, .dol, .elf, .xex. Multi-disc groups (Disc/disk/CD/DVD/side markers) are merged into an .m3u; duplicate ROMs are ranked and the best kept with version_candidates. Existing paths are never duplicated. When emulator choices are supplied, chosen emulators are installed from Flathub. Returns {"added", "found", "recommendations"}; media downloads for entries with a launchbox_db_id are queued respecting media_download_limit.

Like /api/import but also installs each chosen emulator and returns {"added", "found", "recommendations", "installed": [app_ids]}.

Rescan all configured watch folders once. Returns {"added", "found", "errors": [...]}. The background auto-import worker rescans every 10 seconds (backing off to at most 300 on state errors) when the server runs.

{"folder", "command": ""} scans for default.xex, .xex, and .xbe; titles come from the folder name for default.xex. Returns {"added", "found"}.

{"folder", "command": ""} scans .zip, .7z, .singe, .rom files; defaults to hypseus/singe on PATH. Returns {"added", "found"}.

{"folder", "dat": "", "command": "", "source": "MAME"} imports a MAME or FinalBurn Neo full set. With a DAT/XML file, entries are classified as parent, merged, split, or non-merged by comparing set ROMs with the ZIP contents. Without a DAT, MAME's own mame -listxml output is used (300-second timeout, 256 MiB cap) and mame must be installed. Missing folder or catalog raises 400. Returns {"added", "found", "sets": {"parent": n, "merged": n, "split": n, "non-merged": n}}.

{"ready": <database file exists>, "job": {...}} where job is the in-memory metadata sync job (state downloading/done/error, plus error on failure).

Start a background sync of the LaunchBox Games Database (https://gamesdb.launchbox-app.com/Metadata.zip, 2 GiB cap). Returns 202 {"state":"downloading"}; re-POSTing while downloading returns the current job with 200.

?id=<index>&q=<title>&platform=<platform> searches the local database (20 results max). Before the database exists: 409 {"error":"Download the LaunchBox metadata database first."}. Results include database_id, name, platform, release_date, developer, publisher, genre, overview, series, esrb, max_players, cooperative.

{"id"|"game_id", "database_id": <int>, "media": ["cover"|"background"|"screenshots"], "overwrite": bool}. Applies text metadata (name, platform, year, developer, publisher, genre, description, series, ESRB, max_players, launchbox_db_id) and downloads the selected media into media/launchbox/<database_id>/ (cover/background 32 MiB cap; screenshots at most 12). Missing database raises 400. Returns {"updated": [changed_fields]} and bumps the media epoch.

Fetch Steam store metadata (appdetails) for a game with a numeric steam_app_id: name, developer, publisher, genre, year, description, cover, background. Missing App ID raises 400.

Download the first Steam store trailer: requires steam_app_id. Returns {"video_trailer": "<path>"}.

Download GOG cover/background for a Heroic/GOG id. Returns {"cover", "background"}.

?q=<title>&platform=<platform> searches IGDB (requires IGDB_CLIENT_ID/IGDB_CLIENT_SECRET in ~/.env; missing credentials raise 400). Results include id, name, summary, year, genres, platforms, rating, critic_score.

{"id"|"game_id", "igdb_id": <int>} applies name, description, year, genre, developer, publisher, rating, igdb_id, and time_to_beat_hours. Returns {"applied": true, "game": "<name>"}.

Serve one media file: ?id=<index>&kind=cover|background|clear_logo|fanart|banner|icon|box_back|box_spine|box_3d|title_screen|video|music|video_snap|video_theme|video_trailer|video_recording|screenshot&index=<n> (screenshot index for kind=screenshot). kind=video resolves the active video by priority. Missing file or bad kind: 404 {"error":"Media not found"}. Media responses carry immutable cache headers, ETag, and byte-range support.

Start a background media download for every game with a launchbox_db_id (optionally ?platform= scoped): {"media": ["cover"|"background"|"screenshots"], "overwrite": bool}. Returns 202 {"state":"running"}. Missing database raises 400.

{"job": {"state": "running"|"done", "current", "total", "updated", "errors": [...]}} (last 20 errors).

?platform=<name or "all"> reports games, matched (has launchbox_db_id), missing_cover, missing_background, missing_screenshots.

{"groups": [{"keep": "<path>", "duplicates": [...]}]} by SHA-256 + size fingerprint of covers, backgrounds, and screenshots.

{"apply": bool} removes duplicate media. With apply: false it is a dry run returning candidate paths; with apply: true files are deleted (only inside the data directory) and the media epoch bumps. Returns {"groups", "paths": [...], "applied"}.

{"queue": [...]} from media-queue.json (pending media jobs).

Capture the screen with the first available tool among gnome-screenshot, spectacle, scrot, and ImageMagick import; appends to the game's screenshots and bumps the media epoch. Returns {"path"}.

{"emulators": [...], "install_all": {...}}. Each emulator: app_id, name, platforms, installed, mode (native|flatpak|""), profiles (platform to command), can_install (flatpak present), recommendations. The known set is Dolphin, PPSSPP, PCSX2, RPCS3, Cemu, MAME, xemu, ScummVM, RetroArch, DuckStation, melonDS.

?platform=<name> returns {"recommendations": [...]} from the platform-to-emulator map.

?name=<emulator> returns {"required": [...], "missing": [...]} BIOS/system file checks (DuckStation, PCSX2, RPCS3, RetroArch hints).

{"app_id": "org.mamedev.MAME"} installs from Flathub (adding the flathub remote if needed; 120 s remote, 1800 s install timeouts) and merges the platform profiles. Returns 202 {"state":"installing"}; duplicates return 200 with the current job. Errors surface as 400/500 with flatpak's stderr detail.

Install every not-installed emulator. Returns 202 {"state":"installing"}; completion job has {"state":"done", "installed": [...], "errors": [...]}.

{"app_id"} launches the emulator standalone (native binary or flatpak run). Not installed: 400 "<name> is not installed.".

{"definitions": [...]} YAML emulator definition packs (id, name, extensions, platforms, startup, executable_patterns, flatpak, native).

{"folder"} scans a folder using the definitions. Returns {"added", "found"}.

?source=steam|heroic|lutris|gameyfin returns {"catalog": [...]}. Steam reads installed manifests plus owned app ids from localconfig.vdf; Heroic reads library caches; Lutris uses --list-games --json; Gameyfin queries the configured server (requires gameyfin_url in settings, else 400). Entries carry id, name, source, installed, install_uri, path, launch, and store-specific ids. Provider errors return 400.

{"source", "uninstalled_only": bool, "installed_only": bool} imports catalog entries as games (deduplicated by identity), marking store_catalog, store_installed, owned. Returns {"added", "found", "imported"}. Unknown source raises 400.

{"providers": [...]} from the configured server. Connection failures return 400.

Test connection using posted settings (merged over stored). Returns {"ok": true, "games": <n>, "providers": [...]}.

{"gameyfin_id"|"id", "library_id": <optional>} downloads the game from Gameyfin into the install directory (staging with rollback; symlinks rejected; 4 GiB per file cap) and updates or appends the library entry. Returns 202 {"state":"installing", "gameyfin_id"}; without a gameyfin_id raises 400.

?gameyfin_id=<id> returns the job: {"state": "idle"|"installing"|"done"|"error", "gameyfin_id", "error"?}. Missing id raises 400.

Removes the game's install directory and files (refusing symlinks and paths outside the install directory) and marks the entry uninstalled. Non-Gameyfin entries raise 400. Returns {"removed": [...], "game": {...}}.

Library audit: {"games", "missing", "duplicates", "unconfigured", "missing_media", "issues": [...]}. Issues are typed Duplicate, Missing game, Missing box front, Missing extra, Missing save path, and No emulator (ROM extensions without a launch command or platform profile).

Remove duplicate games by identity (steam app id, heroic, lutris, arcade rom_name, or normalized path). Returns {"removed": [names]}.

{"recently_added": [...], "never_played": [...], "short_sessions": [...], "highly_rated": [...], "continue_playing": [...], "random_picks": [...], "generated_at": ...} index lists (12 each).