// OPENBOX DOCS
API saves and operations
Save, backup, sync, and operation-specific status routes.
Save management, library backups, statistics sync, save-tool hooks, high scores, and OBS. Catalog synchronization is documented in Statistics sync. All routes require X-OpenBox-Token: TOKEN; POST bodies are JSON objects. Games are located by id (numeric index) or game_id (stable id).
Save discovery and management
/api/v2/saves?id=<index>&game_id=<stable> returns {"backups": [{"name", "size"}, ...]} for the game, newest first. Unknown game: 404.
/api/v2/saves/discover?id=<index>&game_id=<stable> returns {"candidates": [...]} of save paths found on disk that are not yet configured: {"path", "label", "shared"}. Discovery covers Steam Cloud (userdata/*/<app_id>/remote), shared platform roots (PCSX2 memcards, PPSSPP SAVEDATA, RPCS3 savedata, Dolphin GC/Wii title, Cemu usr/save, RetroArch saves/states, Mednafen), and RetroArch files whose stem matches the game title. On macOS the roots are the Steam Cloud folder under ~/Library/Application Support/Steam, PPSSPP under ~/.config/ppsspp, RPCS3 and Dolphin under ~/Library/Application Support, and RetroArch under ~/Documents/RetroArch; PCSX2, Cemu, and Mednafen have no documented macOS folder and are not searched. See macOS.
/api/v2/saves/scanScan every library game for save paths. Returns {"games": {"<index>": [paths]}, "count": <n>} where <index> is the game's position in the library array (the scan result is keyed by index, not by game_id). When save management is disabled, returns {"enabled": false}.
/api/v2/saves/scan/applyAdd all scanned save paths to each game. Returns 202 {"state": "queued", "job_id": "<id>"} — the scan runs as a durable background job. Poll the job via GET /api/v2/jobs; the worker result carries {"updated": <count>, "games": <n>}.
/api/v2/saves/backupCreate a versioned save backup ZIP. Body: {"id"|"game_id"}. Requirements and behavior:
- At least one configured save path must exist, or
400"No configured save paths currently exist." - Backup paths and sources may not be symlinks (
400otherwise). - The archive is stored under
save-backups/<hash>/<timestamp>-manual.zipwith amanifest.jsonlistinggameandroots(path + whether it is a single file). - After backup, retention applies:
save_backup_limit(default 10, 0..500) trims the oldest archives.
Returns {"backup": "<name>", "trimmed": <removed count>}.
/api/v2/saves/restore{"id"|"game_id", "backup": "<name>"} restores a save backup. Safety behavior:
- An automatic
before-restorebackup is created first. - The backup name is resolved strictly inside the game's backup directory (no path traversal).
- The archive manifest must list roots that match the game's currently configured
save_pathsin the same count and order, or400"Save backup roots do not match this game." - Members are validated: no absolute paths, no
.., no duplicate names, no symlinks in the destination tree, per-member cap 4 GiB, total cap 32 GiB. - Files are written with mode
0o600through atomic copy.
Returns {"restored": "<name>"}.
Added in 1.18.0.
/api/v2/resume/slotStores the per-game save-state slot used by Quick Resume: {"id"|"game_id", "slot": "slot-name"}. A slot is 1–32 letters, digits, -, or _; an empty string removes the override and restores the default capture slot. The game may be resolved by stable id or index, and the write invalidates the state cache. Returns {"ok": true, "game_id", "slot"}; an invalid slot returns 400 RESUME_SLOT_INVALID.
Added in 1.18.0.
/api/v2/saves/manifestInspects one save backup without restoring it: ?id=<index> or ?game_id=<stable>, plus backup=<archive name>. Returns {"archive", "game", "files": [{"archive", "path", "size"}], "manifest": {...}}. The archive is resolved strictly inside the game's backup directory, and an unsafe or missing archive returns 400. When save_management_enabled is false the route returns the disabled response and writes nothing.
/api/v2/saves/restore/previewDescribes what restoring one save backup would change, without writing: {"id"|"game_id", "backup": "<name>", "selected": ["optional/archive/path", ...]}. Returns {"archive", "game", "add", "overwrite", "remove", "missing", "conflict", "unchanged", "counts", "truncated"}. add files are absent on disk, overwrite files exist with a different SHA-256, remove is always empty because a save restore never deletes local files, and missing lists manifest entries the archive no longer contains. Each bucket is capped and counts carries the true totals. A selection must be a non-empty subset of the archive, and an empty or mismatched selection returns 400.
/api/v2/saves/add{"id"|"game_id", "path": "/absolute/save/path"} adds an existing path to the game's save_paths. Nonexistent path: 400. Returns {"path"}.
Save Vault
Save Vault keeps indexed, SHA-256-verified snapshots of a game's saves under <data-dir>/save-vault/. It is separate from the per-game save backups above and is excluded from library backups.
| Route | Behavior |
|---|---|
GET /api/v2/saves/vault | Lists snapshots for ?game_id= (or the vault index when omitted). |
GET /api/v2/saves/vault/status | Vault enabled state, retention, disk use, and the 5 GiB warning. |
GET /api/v2/saves/vault/diff | Compares a snapshot with the live saves. |
POST /api/v2/saves/vault/snapshot | Creates a snapshot. Body {id, game_id, trigger}; trigger is manual, session_close, auto, or pre-restore. session_close and auto require save_vault_enabled. |
POST /api/v2/saves/vault/restore | Restores a snapshot and takes a mandatory pre-restore safety snapshot first. Returns 202 {state: "queued", job_id}. |
POST /api/v2/saves/vault/delete | Deletes one snapshot. |
Settings: save_vault_enabled (default true), save_vault_keep (default 5, 1-50), save_vault_on_close (default false), save_vault_auto_days (default 0, 0-365). Snapshots are capped at 512 MiB and 5,000 files; shared emulator roots are excluded; index.json self-heals. See Save Vault.
Library backups
/api/v2/backup/create{"items": ["library", "settings", "media", "plugins", "themes", "extension_data"], "keep": <int>, "format": 2} creates backups/OpenBoxBackup-<timestamp>.zip. Default items when omitted: library, settings. Behavior:
- Refuses while any game is running:
400"Close running games before creating a backup." - Backs up at most 50,000 members, 4 GiB per member, 32 GiB total.
- Backs up no symlinks (raises on any symlink in the source).
keep(when > 0) rotates oldOpenBoxBackup-*.zipfiles to retain the newestkeep.formatdefaults to 2. Format 2 is the only writable format; a request for format 1 returns410 BACKUP_FORMAT_RETIRED("Backup format 1 is no longer written by OpenBox 2.1. Use a 2.0.x build to create a 1.19-compatible export."). Format 1 archives still restore.
Returns 202 {"state": "queued", "job_id": "<id>"} — backup creation runs as a durable background job. Poll the job via GET /api/v2/jobs (cancel with POST /api/v2/jobs/cancel); the worker result carries {"archive": "<path>", "name": "<filename>"}.
/api/v2/backups{"backups": [...]} newest first, each with name, path, size, created (from the manifest), items, and invalid: true when the archive or manifest cannot be read.
/api/v2/backupDownloads a redacted, portable export of the current library state as a JSON attachment (openbox-portable-redacted-export.json). This is a redacted export (credentials and secrets stripped), not a raw library.json snapshot nor a backup archive; it is useful for inspection and external tooling. The response is streamed with Content-Disposition: attachment; filename=openbox-portable-redacted-export.json.
/api/v2/backup/manifest{"items": ["settings", "library", "media", "plugins", "themes", "extension_data"]}.
/api/v2/backup/restore{"path": "/path/to/OpenBoxBackup-....zip", "items": [...], "force": bool} restores selected items. Path must be a real .zip inside the data directory (or backups/); anything else raises 400. Behavior:
- Refuses while games are running.
- Validates every member: no absolute/
../duplicate paths, no symlink/device modes, member cap 4 GiB, total cap 32 GiB. - When restoring
library, the currentlibrary.jsonis copied tolibrary.before-restore.jsonfirst, and the archive's settings are merged into the restored library state. - An archive older than the current
library.jsonis refused unlessforce: true:400"This backup is older than the current library. Pass force=True to restore it anyway." - Media/plugins/themes/extension-data members are written atomically with mode
0o600under the data directory; symlink destinations are rejected before and after mkdir.
Returns 202 {"state": "queued", "job_id": "<id>"} — restore runs as a durable background job. Poll the job via GET /api/v2/jobs (cancel with POST /api/v2/jobs/cancel); the worker result carries {"restored": ["library", ...]}. Media restores bump the media epoch.
Cloud statistics sync
/api/v2/cloud/syncMerge statistics with the mounted cloud folder (settings.cloud_folder). The route always returns 202 {"state": "queued", "job_id": "<id>"}; when no folder is configured the background job fails with "Configure a cloud sync folder first.". Reads/writes openbox-statistics.json (format 1) under a file lock:
- Merges
play_count,playtime_seconds,last_playedby maximum. progress,rating,favoritefollow the side with the newerlast_played; with no play timestamps the newer file (bygenerated_atvslast_cloud_sync) wins.- Deleted local games are never resurrected.
- The file is written atomically with mode
0o600.
Returns 202 {"state": "queued", "job_id": "<id>"} — the merge runs as a durable background job. Poll the job via GET /api/v2/jobs; the worker result carries {"path", "games", "merged", "synced_at"}.
Save tools (Ludusavi / Hoard)
/api/v2/save-tools/status{"ludusavi": bool, "hoard": bool} presence on PATH.
/api/v2/save-tools/ludusavi{"action": "backup"|"restore"|"backups"|"find", "name"|"id", "path": ""}. Requires the ludusavi binary (400 with the install URL otherwise); unknown actions raise 400. Backup/restore pass --force; path maps to --path. Runs with a 600-second timeout. Returns {"ok", "action", "result", "stderr"} where result is the parsed --api JSON (or {"raw": ...}).
/api/v2/save-tools/hoard{"action": "backup"|"restore"|"list", "name"|"id"}. Requires hoard on PATH. Returns {"ok": true, "action", "output"}.
These actions affect local files and restore is destructive: run backups before restores and verify the tool's own report.
MAME high scores
/api/v2/highscores?id=<index>&game_id=<stable> lists local high-score files for the game's rom_name (or path stem): {"scores": [{"file", "size", "label"}, ...]}. Only meaningful for Arcade/MAME/FinalBurn Neo games. 404 when the game is missing.
Added in 1.18.0.
/api/v2/highscores/tableReturns the parsed MAME high-score table for a game: ?id=<index> or ?game_id=<stable>. The ROM name comes from rom_name or the game path stem, and the matching <rom>.hi file is resolved inside MAME's hi directory with containment enforced. Returns {"source", "path", "name", "size", "label", "rom_name", "parsed", "scores", "message"}. Parsing needs the optional hi2txt tool (10-second timeout); without it, or when no file matches, parsed is false, scores is empty, and message explains why. A missing game returns 404.
/api/v2/highscores/exportExports matching .hi files plus a highscores.json manifest (format 1, exported_at, game, rom, files) into highscores/<slug>/. Returns {"files": [...], "manifest": "<path>"}.
/api/v2/highscores/import{"id"|"game_id", "path": "/dir"} restores .hi files from a folder (or a highscores.json bundle) into the MAME hi directory, prefixing filenames with the ROM name when needed, mode 0o600. Returns {"restored": [...]}; no usable files raise 400.
Media queue and cache
/api/v2/media/queueReturns the durable media download queue snapshot: {"items": [...], "queue": [...], "running", "paused", "completed", "failed", "cancelled", "counts": {"total", "queued", "failed", "completed", "cancelled"}}. items and queue carry the same normalized entries. The snapshot is read from media-queue.json and merged with the worker's in-process counters, so a restarted server still reports queued work.
/api/v2/media/queue/pauseRequests a cooperative pause of the media worker and returns the current worker state (running, paused, cancelled, completed, failed). The in-flight download is allowed to finish; queued items stay queued.
/api/v2/media/queue/resumeClears the pause and cancel flags and starts the worker if it is not alive. Returns the current worker state. Resuming an already-running worker is harmless.
/api/v2/media/queue/cancelRequests cancellation of the media worker and clears the pause flag. Returns the current worker state; queued items remain in the queue and can be resumed later.
/api/v2/media/queue/retryRequeues one failed download: {"id": "<queue item id>"}. The item's attempts and error are cleared, and the worker starts if it is idle. Returns {"ok": true, "id"}; a missing id or an unknown item raises 400.
/api/v2/media/cache/cleanupDeletes generated media-cache files older than days: {"days": 30} (default 30, clamped to 1–3650). Only regular files under <data>/cache/media are touched; user media and symlinks are never removed. Returns {"root", "deleted", "bytes", "skipped"}.
OBS
/api/v2/obs/status{"running": bool, "recording": bool, "directory": "<obs output dir>", "latest_recording": "<path or null>"}. The directory is read from the newest OBS profile's basic.ini (SimpleOutput/AdvOut FilePath/RecFilePath), falling back to ~/Videos.
/api/v2/obs/attach{"id"|"game_id", "path": "/path/to/recording.mp4"} attaches a recording file as video_recording (and video when no video is set). Missing file: 400. Returns {"path", "obs": {status}}.
Screenshot and capture
/api/v2/screenshotCapture the screen with the first available tool among gnome-screenshot, spectacle, scrot, and ImageMagick import; appends the PNG to the game's screenshots under media/captures/ and bumps the media epoch. Returns {"path"}; no tool available raises 400.
RetroAchievements
/api/v2/ra/settings{"configured": false} when no credentials exist; otherwise fetches the user profile and returns {"configured": true, "username", "points", "motto"}. Profile API failures return 400.
/api/v2/ra/settings{"username", "api_key"} validates against API_GetUserProfile.php and persists to retroachievements.json (mode 0o600). Rejected credentials raise 400 "RetroAchievements rejected those credentials." — RetroAchievements 401/403 responses are translated to that message instead of a generic HTTP failure, and a profile without a User fails the same way. Returns the profile summary.
/api/v2/ra/gameMatch a game to RetroAchievements (requires credentials): computes the ROM hash (with header stripping for NES/SNES/7800/Lynx/PC Engine, byte swaps for N64, archive ROM extraction for ZIP/7z) and returns API_GetGameInfoAndUserProgress enriched with beaten/mastered totals and points. Missing credentials: 400 "Configure RetroAchievements first."; unmatched hashes raise 400.
/api/v2/ra/injectWrite credentials into emulator configs (RetroArch cheevos_*, Dolphin, PCSX2) for both native and Flatpak paths. Returns {"updated": [...], "skipped": [...]}.
/api/v2/ra/badge?name=<badge>&locked=0|1 serves a badge PNG, downloading it on demand from media.retroachievements.org. Unknown badge: 404.
Added in 1.18.0.
/api/v2/achievements/refreshRefreshes one non-RetroAchievements achievement source for a game: {"game_id": "<stable>", "source": "steam"} or "source": "plugin:<plugin-id>:<source>". RetroAchievements is rejected here because ROM matching uses POST /api/v2/ra/game; Steam requires steam_app_id and saved Steam credentials. Returns {"ok": true, "game_id", "source"} and invalidates the state cache. A plugin source refreshes that plugin's cached statistics.
/api/v2/achievements/overrideWrites or clears a manual achievement override: {"game_id", "source", "earned", "total", "mastered", "clear"}. source is retroachievements, steam, gog, or plugin:<id>. Totals must satisfy 0 <= earned <= total <= 10000; mastered defaults to earned == total when total is greater than zero. clear: true removes that source's override and returns {"ok": true, "cleared": true}. A successful write returns the stored {"source", "earned", "total", "mastered", "manual"} shape.
Bezels and EmuMovies
/api/v2/bezels/download{"platform"} downloads and safely extracts the Bezel Project set for the platform (NES, SNES, Nintendo 64, Game Boy Advance, Sega Genesis, PlayStation, Arcade). Unknown platform raises 400. Returns {"path"}.
/api/v2/emumovies/settings{"username", "password"} persists EmuMovies credentials to emumovies.json (mode 0o600). Returns {"configured": true}.
/api/v2/emumovies/download{"id"|"game_id", "type": "box"} downloads media from EmuMovies with basic-auth credentials (32 MiB cap, image content type enforced). Missing credentials raise 400 "Configure EmuMovies credentials in Settings first.". Returns {"path"}.
/api/v2/backup/diffCompare the current library state against a named backup archive. Query parameter: archive=<name> (the backup archive name as listed by GET /api/v2/backups).
Returns {"added": [...game_ids], "removed": [...game_ids], "changed": [...game_ids], "settings_changed": <bool>, "summary": {"added": <count>, "removed": <count>, "changed": <count>, "total": <count>}} (total is the current library game count).
added: games present in the current library but not in the backup.removed: games present in the backup but not in the current library.changed: games present in both but with differing fields.settings_changed: whether app settings differ between backup and current state.
A missing archive parameter returns 400 {"error":"archive parameter required"}; a well-formed archive name that does not exist returns 404. (v1.7.2+)
Restore Preview (v1.16.0+). The three flat lists name the same three sets relative to the current library, which makes them easy to read backwards. The restore block names them the way a user experiences a restore, and it is the only one the UI reads:
{
"restore": {
"will_remove": { "total": 12, "truncated": false, "rows": [{ "game_id": "...", "name": "..." }] },
"will_add": { "total": 3, "truncated": false, "rows": [{ "game_id": "...", "name": "..." }] },
"will_change": { "total": 1, "truncated": false,
"rows": [{ "game_id": "...", "name": "...",
"fields": [{ "field": "progress", "from": "Playing", "to": "Beaten" }] }] }
},
"settings": {
"restored": true, "present": true, "would_change": true, "differs": true,
"redacted_secrets": true, "keys_changed": ["metadata_provider"]
},
"truncated": { "added": false, "removed": false, "changed": false, "limit": 200 }
}
will_removeis games you have now that the backup lacks — what a restore would delete. Note this is theaddedlist above; the two vocabularies are deliberately both present.will_changerows carry per-fieldfrom/todetail.settings.would_changeanswers the user's question — would a restore move my settings? — which is not the same asdiffers, because a library-only backup can differ without the restore being able to act on it.truncatednames which list lost rows;totalis always the true count, so a long list never looks smaller than it is.
Errors
Missing games return 404; destructive operations validate prerequisites before touching files; provider and tool failures return 400 with the exact reason. An unreachable metadata database during LBDB sync fails the job with "Could not reach the metadata database (<reason>). Check the connection and try again." instead of a raw socket message. See REST API overview for the shared envelope and Save archives / Library backups for the archive contracts.