API 1.11 additions

OpenBox 1.11.0 adds these authenticated, additive /api/v2/* workflows without changing the frozen v1 contract. The server still binds to loopback, chooses a random port at launch, and accepts X-OpenBox-Token: TOKEN on every protected route.

DATA_DIR="$HOME/.local/share/openbox-game-launcher"
TOKEN=$(cat "$DATA_DIR/server.token")
PORT=$(cat "$DATA_DIR/server.port")
BASE="http://127.0.0.1:$PORT"

Use the header form in scripts. The query-string token is accepted for the browser launch path but can leak into history and logs. POST bodies are JSON objects and are subject to the shared 65,536-byte body limit. Durable operations return 202 with a job_id; inspect them through the jobs endpoints documented in Saves and operations. On Windows the data directory is %LOCALAPPDATA%\openbox-game-launcher, so server.token and server.port live there instead.

Quick Resume and Moments

Quick Resume reports adapter capability and state freshness before loading a saved emulator state. Pass allow_stale: true only when you have reviewed the adapter or emulator-version mismatch.

Moments are bounded timeline records attached to one game. A capture can include a screenshot when the host supports it, but the note and trigger remain durable when capture is unavailable.

Example:

curl -s -X POST "$BASE/api/v2/moments" \
  -H "X-OpenBox-Token: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"game_id":"GAME_ID","title":"Boss attempt","note":"Try the left route next time","trigger":"manual"}'

Record That: clips and reels

The clip capture route uses the configured OBS replay buffer when enabled and falls back to a local screenshot clip when OBS is unavailable. Returned clip paths are approved local media paths, not arbitrary file reads.

Time Machine and query grammar

Time Machine is journal-backed and bounded. Reads do not mutate the library. Reverts are preview-first: the response contains a plan and base_token; send that reviewed plan back with apply: true and the current base token. A stale plan returns 409 and must be previewed again.

Preview a revert before applying it:

curl -s -X POST "$BASE/api/v2/library/time-machine/revert" \
  -H "X-OpenBox-Token: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"event_id":"EVENT_ID"}'

Backlog Radio and launcher trophies

Backlog Radio and Radar use local library and history data. They do not call a remote recommendation service.

Launcher trophies are deterministic OpenBox milestones over local library and history data. They are not RetroAchievements, do not require an account, and do not submit data to a service.

Each radio pick and radar entry carries estimated_minutes (integer, rounded): the genre-based length estimate minus already-played minutes (floor 15; unplayed games report the full estimate). Picks hydrated from the stored managed playlist carry it too, with a frontend fallback for older entries. The genre fallback when no history exists is RPG/strategy/simulation 120 min, adventure/action/shooter/platform/fighting 60 min, puzzle/card/board 30 min, and 45 min otherwise; a game fits a requested session when its median session (or the fallback estimate) is at most 1.5x the requested minutes.

GET /api/v2/insights/wrapped returns the year-in-review "wrapped" payload assembled from the session journal, playtime, and completion data. It is a pure read projection: nothing is written, so the summary can never go stale.

year is a required query parameter naming the calendar year to summarize. Omitting it returns 400 ("year is required"); a non-integer returns 400 ("year must be an integer"), and a year outside 1970-2100 returns 400 ("year must be between 1970 and 2100"). Example: /api/v2/insights/wrapped?year=2026.

Game Night party queue

Game Night builds a couch-multiplayer queue from the local library. Since 1.12.1 an empty build explains itself instead of returning a bare empty list.

{
  "queue": [],
  "count": 0,
  "empty_reason": "No games support 6 players — lower the player count or add Max players metadata.",
  "excluded": {"total": 120, "hidden": 4, "unusable_path": 10, "too_few_players": 96, "no_controller_or_platform": 8, "over_budget": 2}
}

empty_reason is null when the queue is non-empty; the top exclusion reason wins (empty library, too few players, no couch-ready titles, missing files, over-budget sessions, all hidden). Non-object bodies and non-integer or out-of-range players/minutes return 400.

Arcade Room and Museum kiosk

Arcade Room exposes the controller-first showroom state. The optional kiosk PIN is a convenience boundary for a local Museum presentation; it is not a replacement for the API session token or a security boundary.

Household records and sync

Household is local-first. It stores members, challenges, results, and opt-in shares in the local state and can exchange validated records through the configured mounted sync folder. It does not provide hosted accounts or real-time multiplayer.

Steam Bridge and ES-DE migration

Both integrations are review-first and preserve foreign data. Preview responses include a plan or import decisions; apply only the reviewed plan against an unchanged source. A changed source returns a conflict instead of silently overwriting it. Steam Bridge reports a stale preview as HTTP 409 with STEAMBRIDGE_PREVIEW_STALE; ES-DE reports its stale-plan condition as HTTP 400 with ESDE_STALE_PLAN. In either case, preview again before applying.

SteamGridDB artwork

SteamGridDB is optional. Set STEAMGRIDDB_API_KEY in ~/.env, enable the provider in Settings, and restart OpenBox after changing the environment file. Search and apply use a bounded local cache; apply and bulk match return durable job IDs.

The supported media kinds are cover, background, clear_logo, icon, and banner. Provider artwork is written into OpenBox-managed media paths; credentials are never returned in API responses.

Compatibility and error handling

All routes on this page are additive v2 routes. The frozen /api/v1/* surface remains unchanged. The shared API contract still applies:

• 403 {"error":"Unauthorized"} means a known protected route received no valid token; an unknown route can resolve to 404 before auth.
• 409 is used for stale review plans or launch/state conflicts where the operation must be previewed or retried.
• 202 {"state":"queued","job_id":"…"} means the local durable-operation manager accepted the work; query /api/v2/jobs for progress.
• 400 responses identify validation failures with the route's error message and, for structured errors, a stable code.
• 503 means local state or an explicitly required integration is unavailable; no destructive mutation should be inferred from the response.

See REST API overview for the request lifecycle, REST API for group navigation, and the corresponding user guides for UI-level workflows.