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

GET/api/v2/saves

?id=<index>&game_id=<stable> returns {"backups": [{"name", "size"}, ...]} for the game, newest first. Unknown game: 404.

GET/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.

GET/api/v2/saves/scan

Scan 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}.

POST/api/v2/saves/scan/apply

Add 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>}.

POST/api/v2/saves/backup

Create 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 (400 otherwise).
  • The archive is stored under save-backups/<hash>/<timestamp>-manual.zip with a manifest.json listing game and roots (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>}.

POST/api/v2/saves/restore

{"id"|"game_id", "backup": "<name>"} restores a save backup. Safety behavior:

  • An automatic before-restore backup 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_paths in the same count and order, or 400 "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 0o600 through atomic copy.

Returns {"restored": "<name>"}.

Added in 1.18.0.

POST/api/v2/resume/slot

Stores 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.

GET/api/v2/saves/manifest

Inspects 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.

POST/api/v2/saves/restore/preview

Describes 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.

POST/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.

RouteBehavior
GET /api/v2/saves/vaultLists snapshots for ?game_id= (or the vault index when omitted).
GET /api/v2/saves/vault/statusVault enabled state, retention, disk use, and the 5 GiB warning.
GET /api/v2/saves/vault/diffCompares a snapshot with the live saves.
POST /api/v2/saves/vault/snapshotCreates 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/restoreRestores a snapshot and takes a mandatory pre-restore safety snapshot first. Returns 202 {state: "queued", job_id}.
POST /api/v2/saves/vault/deleteDeletes 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

POST/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 old OpenBoxBackup-*.zip files to retain the newest keep.
  • format defaults to 2. Format 2 is the only writable format; a request for format 1 returns 410 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>"}.

GET/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.

GET/api/v2/backup

Downloads 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.

GET/api/v2/backup/manifest

{"items": ["settings", "library", "media", "plugins", "themes", "extension_data"]}.

POST/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 current library.json is copied to library.before-restore.json first, and the archive's settings are merged into the restored library state.
  • An archive older than the current library.json is refused unless force: 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 0o600 under 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

POST/api/v2/cloud/sync

Merge 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_played by maximum.
  • progress, rating, favorite follow the side with the newer last_played; with no play timestamps the newer file (by generated_at vs last_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)

GET/api/v2/save-tools/status

{"ludusavi": bool, "hoard": bool} presence on PATH.

POST/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": ...}).

POST/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

GET/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.

GET/api/v2/highscores/table

Returns 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.

POST/api/v2/highscores/export

Exports matching .hi files plus a highscores.json manifest (format 1, exported_at, game, rom, files) into highscores/<slug>/. Returns {"files": [...], "manifest": "<path>"}.

POST/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

GET/api/v2/media/queue

Returns 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.

POST/api/v2/media/queue/pause

Requests 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.

POST/api/v2/media/queue/resume

Clears 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.

POST/api/v2/media/queue/cancel

Requests 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.

POST/api/v2/media/queue/retry

Requeues 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.

POST/api/v2/media/cache/cleanup

Deletes 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

GET/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.

POST/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

POST/api/v2/screenshot

Capture 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

GET/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.

POST/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.

POST/api/v2/ra/game

Match 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.

POST/api/v2/ra/inject

Write credentials into emulator configs (RetroArch cheevos_*, Dolphin, PCSX2) for both native and Flatpak paths. Returns {"updated": [...], "skipped": [...]}.

GET/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.

POST/api/v2/achievements/refresh

Refreshes 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.

POST/api/v2/achievements/override

Writes 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

POST/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"}.

POST/api/v2/emumovies/settings

{"username", "password"} persists EmuMovies credentials to emumovies.json (mode 0o600). Returns {"configured": true}.

POST/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"}.

GET/api/v2/backup/diff

Compare 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_remove is games you have now that the backup lacks — what a restore would delete. Note this is the added list above; the two vocabularies are deliberately both present.
  • will_change rows carry per-field from / to detail.
  • settings.would_change answers the user's question — would a restore move my settings? — which is not the same as differs, because a library-only backup can differ without the restore being able to act on it.
  • truncated names which list lost rows; total is 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.