// OPENBOX DOCS
API local administrator
Local administrator operations that are not a stable remote contract.
These routes manage the local installation and process. They are not a stable remote contract: treat them as local-administrator operations and verify behavior against the running version. All require X-OpenBox-Token: TOKEN; POST bodies are JSON objects.
Updates
/api/v2/updateCheck for a new release. Queries the GitHub releases API for vindeckyy/OpenBoxGL (30-second timeout) and returns:
{
"current": "1.18.0",
"latest": "1.18.0",
"available": false,
"last_checked": "<timestamp or empty>",
"notes": "...",
"appimage": "https://github.com/vindeckyy/OpenBoxGL/releases/download/.../OpenBox-x86_64.AppImage",
"checksum": "sha256:...",
"checksum_url": "...",
"sig": true,
"sig_url": "...",
"page": "https://github.com/.../releases/tag/..."
}
Rules:
- Pre-release and build-suffixed tags are never
available. - The AppImage asset matching the running architecture (
OpenBox-x86_64.AppImageorOpenBox-aarch64.AppImage) must come from the trustedhttps://github.com/vindeckyy/OpenBoxGL/releases/download/prefix and a SHA-256 checksum must be present (asset digest or.sha256file); otherwise400with a clear reason. sigis a boolean indicating that a trusted.sigasset exists;sig_urlcontains its URL. A missing or untrusted signature makes an available update fail closed.- GitHub failures return
400("GitHub releases request failed (...)"/"Could not reach GitHub releases: ..."). SettingGITHUB_TOKEN(orGH_TOKEN) in~/.envauthenticates the request for a higher rate limit.
/api/v2/update/installDownload and atomically install the verified update into the running AppImage. Prerequisites:
APPIMAGEmust be set (the process must run from an AppImage), else400"Automatic updates require the OpenBox AppImage."- The update must be
availableand its URLs trusted. - The download streams with a 512 MiB cap and the SHA-256 is verified before the swap.
- The current AppImage is renamed to
<name>.previous<ext>; a failed swap restores it.
Returns {"installed": "<version>", "backup": "<path>"}. Restart to use the update.
The 3.0 Rust server implements the verified install step for the AppImage only. On Windows it returns "Automatic updates require an installed OpenBox copy."; on macOS it returns "Automatic updates require the OpenBox.app bundle.". Install a new release with the new release's install.ps1 or install-macos.sh --replace.
Shutdown
/api/v2/shutdownRequests shutdown and returns {"ok": true, "shutting_down": true}. The 3.0 handler does not accept a force field or report a stopped-game count; the server tears down its sessions as part of shutdown. The same handler is mounted at POST /api/host/shutdown for the native windows.
State recovery
/api/v2/state/recoverRestore the library from library.json.bak or rolling snapshots (see Data and recovery).
- Inspect: Body
{"dry_run": true}returns available backups and snapshots:{"dry_run": true, "backup_available": bool, "games": int, "snapshots": [{"name", "size", "modified"}]}. - Restore backup: Body
{}restoreslibrary.json.bakand returns{"ok": true, "games": int}. - Restore snapshot: Body
{"snapshot": "<name>"}restores the specified snapshot. An unusable backup or unknown snapshot raises an error message.
Desktop integration
/api/v2/desktop/installWrite the desktop entry and icon for the running AppImage: ~/.local/share/applications/io.openbox.GameLauncher.desktop and ~/.local/share/icons/hicolor/scalable/apps/io.openbox.GameLauncher.svg. Requires APPIMAGE (else 400). Returns {"desktop": "<path>"}.
Native status and display video
/api/v2/native/batteryReports battery state for the native window: {"present": bool, "percent": 0-100, "charging": bool}. On Linux the first BAT* device under /sys/class/power_supply is read; on macOS pmset -g batt is read; on Windows GetSystemPowerStatus is read. The response never exposes the device path. A host with no battery, such as a desktop, returns {"present": false, "percent": 0, "charging": false}. See API 1.19 changes.
/api/v2/bigbox/startup-videoStreams the configured bigbox_startup_video when it is an existing .mp4, .webm, .ogv, .ogg, or .mkv file. An empty setting, a missing file, or an unsupported suffix returns 404 {"error": "Startup video not found"}. The video path itself is not echoed in the response.
/api/v2/platform/videosReturns the configured per-platform video map: {"videos": {"SNES": "/absolute/path.mp4", ...}}. A malformed stored value is treated as an empty map.
/api/v2/platform/videoStreams one platform video: ?platform=<name>. The stored path must still be an existing supported video file; a missing platform, path, or file returns 404 {"error": "Platform video not found"}.
/api/v2/platform/videosSets or clears one platform video: {"platform": "SNES", "path": "/absolute/video.mp4"} or {"platform": "SNES", "clear": true}. The platform is required and capped at 80 characters; the path must be absolute, existing, and end in .mp4, .webm, .ogv, .ogg, or .mkv. Returns {"platform", "path"} with an empty path after a clear.
Themes
/api/v2/themes?platform=<name> returns {"themes": [...], "selected": "...", "global": "...", "mappings": {...}}. Stock themes are installed on demand (Midnight Circuit, Phosphor Terminal, Harbor Light, Cinema Marquee, Nordic Mist). selected is the per-platform mapping when platform is given, else the global theme.
/api/v2/themes/select{"name": "theme-name"|"", "platform": ""} sets the global theme (or clears it with ""); with platform, sets/clears a per-platform mapping. Unknown theme file: 400. Returns {"selected", "platform"}.
/api/v2/themes/import{"path": "/path/to/theme.css"} copies a CSS file into themes/ (.css suffix required, max 256 KiB, must be valid UTF-8, symlinked sources/destinations rejected, remote @import with http rejected to respect style-src CSP). Returns {"theme": "<stem>"}. Errors: 400 with the exact reason when the file is missing, too large, a symlink, or contains a remote import.
/api/v2/themes/open-folderOpen the themes folder in the file manager via xdg-open (missing xdg-open: 400). Returns {"path"}.
Added in 1.18.0.
/api/v2/theme-sounds?name=<theme stem> reads the theme's optional <theme>.json sidecar and returns {"music": "<relative path>", "sounds": {"move": "...", "select": "...", "back": "..."}}. Only relative .ogg, .mp3, and .wav paths inside the theme folder are accepted; a missing theme, missing sidecar, malformed JSON, or oversized sidecar returns empty values rather than an error.
/api/v2/theme-assetStreams one theme audio asset: ?name=<theme stem>&path=<relative audio path>. The path is contained to the theme folder, must be an existing .ogg, .mp3, or .wav file no larger than 20 MiB, and is served with a private one-hour cache. A missing theme, non-audio suffix, escape attempt, or oversized file returns 404 {"error": "Theme sound asset not found."}.
Plugins
/api/v2/plugins{"plugins": [{"id", "name", "version", "entry", "hooks", "enabled", "valid", "sandbox", ...}, ...]} sorted by id. Invalid packages are not hidden: they are reported with valid: false and a sandbox status so the manager can explain why they cannot run.
/api/v2/plugins/install{"path": "/path/to/plugin-dir-or.zip"} installs or updates a plugin package (safe extraction, staging, rollback on failure). Returns {"plugin": {...manifest..., "updated": bool}}.
/api/v2/plugins/toggle{"id", "enabled": bool} enables/disables a plugin (persisted in plugins-state.json). Returns {"enabled": bool}.
/api/v2/plugins/remove{"id"} moves the plugin directory to plugins/.removed/<id>-<timestamp> (reversible by moving it back) and clears its disabled state, trust grant, and permission grants. Returns {"removed": "<id>"}.
/api/v2/plugins/catalog{"catalog": [...]} from the commit-pinned remote catalog (20-second timeout, 4 MiB cap, and a pinned SHA-256 check on the response), falling back to the bundled local catalog.
/api/v2/plugins/catalog/install{"id"} downloads the catalog entry's package (128 MiB cap, SHA-256 verified when the entry provides one, 120-second timeout) and installs it. Unknown id or local_only entries raise 400 ("This catalog entry is documentation-only. Install local plugin packages manually."). Returns {"plugin": {...}}.
See Plugins for the manifest and hook contract.
Plugins 2.0 routes (1.14.0+)
/api/v2/plugins/catalogThe catalog enriched per entry with installed, installed_version, and update_available, plus a top-level sandbox field reporting the sandbox mode the host will use (ready, unavailable, or disabled).
/api/v2/plugins/commands{api_version, sandbox, commands} — the manifest-declared commands from enabled, valid plugins, consumed by the command palette.
/api/v2/plugins/command{plugin_id, command} runs that plugin's command hook in the sandbox and returns its result plus any notification. Unlike the chained hooks, a failure surfaces to the caller.
/api/v2/plugins/trust?id=<plugin id> returns the per-plugin trust record: {trusted, checksum, checksum_matches, granted_at}. Trust is only reported true while the recorded checksum still matches the installed package.
/api/v2/plugins/trust{id, trusted} grants or revokes unsandboxed-execution trust for one plugin, recording the package SHA-256 at grant time. There is no trust-everything switch.
/api/v2/plugins/permissions{id, permissions} records a permission grant. Requested permissions must be in the whitelist (network in 1.14.0) and declared by the manifest; anything else returns 400.
/api/v2/plugins/settings?id=<plugin id> returns {schema, values} for the Plugins manager form: the manifest's validated settings schema and the stored values merged over schema defaults.
/api/v2/plugins/settings{id, values} validates and stores per-plugin settings against the manifest schema. An unknown key, an out-of-enum value, or a type/range violation returns 400.
Plugin storage, statistics, and repair
/api/v2/plugins/credentials?id=<plugin id> returns credential key names only: {"id", "credentials": {"keys": [...], "set": {"key": true}}}. Values are stored in a 0o600 file and never travel back to the browser. A missing or malformed store yields empty keys.
/api/v2/plugins/credentialsMerges capability credentials: {"id": "<plugin id>", "values": {"key": "secret"}, "clear": ["old-key"]}. An empty string or null value deletes that key, as does an entry in clear. Names are short strings, values are at most 4,096 characters, and a plugin may store at most 128 credentials. Returns {"id", "credentials": {"keys": [...], "set": {...}}}; values are never echoed.
/api/v2/plugins/data?id=<plugin id> returns one plugin's bounded data bag: {"id", "data": {...}}. This is plugin-owned state, not credentials. A missing or invalid store yields {}.
/api/v2/plugins/dataShallow-merges a patch into one plugin's data bag: {"id": "<plugin id>", "values": {...}}. The merged bag must stay under 1 MiB and four levels deep; an invalid key, excessive depth, or oversized result raises 400 and writes nothing. Returns {"id", "data": {...}}.
/api/v2/plugin-statsReturns the latest cached statistics supplied by enabled plugins: {"sources": [...]}. Each source is the plugin's validated summary; a plugin that has never refreshed reports no rows rather than an error.
/api/v2/plugin-stats/refreshRefreshes plugin statistics: {"plugin_ids": ["<id>", ...]} (at most 64) or the single-key shorthand {"plugin_id": "<id>"}. Unknown or failing plugins are reported per id in {"results": [...]}, so one failure does not abort the batch. Each hook is bounded to 15 seconds.
/api/v2/plugins/repairReinstalls one plugin from its catalog entry without touching its data, credentials, trust, or settings: {"id": "<plugin id>"}. When the catalog entry is missing or local-only, the package is reinstalled from the local package recorded at install time; the repair fails only when that recorded package is unavailable. Returns {"plugin": {...}, "repaired": true}.
Premium read models
/api/v2/premium/strings?locale=en|es|de|fr|pt returns {"locale", "strings": {...}}; unknown locales fall back to English.
/api/v2/premium/media-packs{"packs": [{"id", "name", "description", "kinds", "active"}, ...]}. Bundled packs: clear-logos-default, controller-xbox, controller-playstation, badges-core.
/api/v2/premium/platform-categories{"categories": {...}} platform-to-category mapping (Nintendo, Sony, Microsoft, Computer, Arcade, Adventure, ...) with user overrides merged.
/api/v2/premium/media-packs/apply{"id": "<pack id>"} activates a pack (and sets the controller prompt pack/hint for controller packs). Unknown pack: 400. Returns {"pack": {...}, "settings": {...}}.
Local reads
/api/v2/log{"log": "<last 250 KB of openbox.log>"}. The log redacts tokens, passwords, API keys, and authorization headers, but can contain game names and local file paths.
/api/v2/theme.css?name=<theme> serves the theme CSS with revalidation headers; unknown themes return an empty stylesheet.
/api/v2/diagnosticGET /api/v2/diagnostic returns a sanitized diagnostic preview built by the Rust crash-report builder. It includes the app version, install channel, architecture, distro, desktop session, native-host and renderer flags, library count, schema version, disk space, package integrity, recent job and request IDs, and a system object with python: "rust-native", platform, machine, data directory, and library size. All secrets, tokens, passwords, and API keys are redacted.
report is a JSON-encoded string (clients must JSON.parse it):
{
"report": "{\"report\": \"openbox-diagnostic\", \"version\": \"3.0.0\", \"install_channel\": \"appimage\", \"architecture\": \"x86_64\", \"library_count\": 42, \"schema_version\": 7, \"system\": {\"python\": \"rust-native\", \"platform\": \"linux\", \"data_dir\": \"~/.local/share/openbox-game-launcher\", \"library_bytes\": 1234567}}"
}
GET /api/v2/log returns the last 64 KiB of openbox.log as {"log": "..."}.
/api/v2/jobsGET /api/v2/jobs returns a cursor-paginated list of durable operations (auto-import, metadata-sync, media-bulk, emulator-install, trail-refresh, and others). Query parameters: limit (default 50, max 100), cursor, type or type_filter, state or state_filter, root_job_id, and group_by=root_job_id.
{
"cursor": "",
"next_cursor": "…",
"jobs": [
{
"job_id": "job-abc123",
"type": "metadata-sync",
"state": "running",
"started_at": "2026-08-17T12:00:00Z",
"attempt": 1
}
]
}
Per-operation rows are at GET /api/v2/jobs/items?job_id=…. POST /api/v2/jobs/cancel, /retry, and /resume return 202 with the updated row. The legacy job-name map and GET /api/jobs are gone.
/api/v2/native/capabilitiesReturns native host capabilities detected by the backend when running inside the native wrapper (WebKitGTK on Linux, WebView2 on Windows, WKWebView on macOS), plus the identity fields Settings → About displays. The native windows use GET /api/host/capabilities; the browser-safe mirror is GET /api/v2/native/capabilities. The payload shape is the same on every platform; gamepad stays "webkit" because the host's gamepad hook is a stub and the Web Gamepad API keeps serving. The response also carries a features object that says which platform-specific controls this host supports; a missing object means every feature is unavailable.
{
"webview": true,
"dialogs": true,
"tray": true,
"single_instance": true,
"gamepad": "webkit",
"fullscreen": true,
"clipboard": true,
"version": "3.0.0",
"platform": "win32",
"data_dir": "C:\\Users\\<you>\\AppData\\Local\\openbox-game-launcher",
"features": { "gamescope": false, "mangohud": false, "wine": false, "faugus": false, "lutris": false, "heroic": true, "native_storefronts": true, "desktop_entry": false }
}
webview is what Settings → About reads to say whether you are in the native window or a browser tab — a browser tab is a supported configuration, not a failure state.
/api/v2/native/dialogOpens a native file or folder picker dialog on the host system. Body: {"kind": "folder" | "file" | "save"} (defaults to "folder"). Returns {"path": "/selected/path"} or {"path": null, "cancelled": true}. Unauthorized requests return 403 {"error": "Unauthorized"}.
/api/v2/native/revealReveals a file or folder in the default desktop file manager (e.g. Nautilus, Dolphin). Body: {"path": "/path/to/game.rom"}. Returns {"ok": bool, "error": str | null}.
/api/v2/native/open-externalOpens an external HTTP/HTTPS URL or file path in the host's default web browser or application. Body: {"url": "https://..."} or {"path": "/path/to/file"}. Returns {"ok": bool, "error": str | null}.
/api/v2/native/windowControls the native application window. Body: {"action": "minimize" | "toggle-maximize" | "close" | "set-fullscreen" | "unset-fullscreen"}. Returns {"ok": bool}.
/api/v2/platform/documentsRetrieves the document metadata list for a platform (?platform=<name>) or mapping of all platforms when omitted. Returns {"documents": [{"name", "path"}, ...]}.
/api/v2/platform/documentServes a platform document file for inline viewing (?platform=<name>&index=<doc_index>). Symlinks are rejected. Missing document returns 404 {"error": "Platform document not found"}.
/api/v2/platform/documents{"platform", "documents": [{"name", "path"}, ...]} replaces the platform's document list (capped at 100 entries). Returns {"saved", "count"}.
/api/v2/documentServes a game's document file for inline viewing (?id=<index>&index=<doc_index> or ?game_id=<id>&index=<doc_index>). The file is validated to be a regular file (symlinks rejected), served with its guessed MIME type and a sanitized Content-Disposition name. Missing game, index, or file returns 404 {"error": "Document not found"}.
/api/v2/explorer/facetsFacet counts for the Explorer rail (?field=genre|developer|publisher|platform|progress|esrb). Hidden games are skipped; missing values fall back to Unspecified / Unplayed / Unrated; results are sorted by count descending then name, capped at 40. Returns {"field", "facets": [{"value", "count"}, ...]}. Unknown fields return an empty list.
/api/v2/bigbox/modeSignals Big Box mode entry or exit. Body {"entering": true} runs the configured bigbox_shutdown_commands in new session groups (failures are logged, never block). Body {"entering": false} acknowledges mode exit. Returns {"ok": true, "entering": bool, "commands": <count>}; commands is the number of exit commands run.
Errors
These routes fail loudly on missing prerequisites (400 with the exact requirement) and never silently skip destructive steps. See REST API overview for the shared envelope.