// OPENBOX DOCS
REST API overview
Loopback boundary, authentication, body limits, and the request lifecycle.
The Rust server (openbox-server) binds to 127.0.0.1 on an ephemeral port, or the port in OPENBOX_PORT. This page documents the shared contract every route follows and the lifecycle a request goes through. Route lists live on the group pages. The public surface is /api/v2/*; the native windows use /api/host/*.
Loopback boundary
- The server binds to
127.0.0.1only, so nothing is reachable from the network.OPENBOX_PORTcan pin the port; the default is0. - OpenBoxGL does not terminate HTTPS. Use a trusted network and an external reverse proxy if you must expose it beyond the host.
- Requests carry a 30-second timeout.
- The public GET surface is
/,/index.html,/static/*.js|*.svg,/static/app.css,/static/logo.png,/assets/placeholder-cover.svg,/locales/{en,es,de,fr,pt}.json,/favicon.ico, and/favicon.svg. Every other route requires authentication.
Authentication
All API routes require the session token. The server writes it to server.token in the data directory at startup and deletes the file on exit. Two transports are accepted:
- Header:
X-OpenBox-Token: TOKEN(preferred) - Query parameter:
?token=TOKEN(can leak through history and logs)
The token is compared in constant time. Authentication runs before the host-version guard, the retired-route guard, and route resolution, so an unknown route without a token returns 403, not 404. A missing or wrong token returns 403 {"error":"Unauthorized"}. Ten failures in 60 seconds per IP return 429 with code: "RATE_LIMITED", retry_after, and a Retry-After header; a correct token clears the bucket.
Request lifecycle
A request flows through a fixed set of stages. Knowing the order tells you which status code you will get and why:
request
├─ host header not loopback? → 403 BAD_HOST
├─ public GET path? → serve asset, no token
├─ method not GET/POST? → 404 ROUTE_NOT_FOUND
├─ missing/wrong token? → 403 Unauthorized (429 RATE_LIMITED after 10/60s)
├─ /api/host/* with X-OpenBox-API-Version major ≠ 2? → 409 HOST_API_UNSUPPORTED
├─ /api/v1/* → 410 V1_API_REMOVED
├─ legacy host path → 410 HOST_CHANNEL_RETIRED
├─ unversioned /api/* with a v2 twin → 410 API_VERSION_REQUIRED
├─ POST body over 65,536 bytes or not a JSON object → 400
├─ state schema <7 / >7 / frozen → 409 STATE_SCHEMA_TOO_OLD / STATE_FUTURE_VERSION / LIBRARY_FROZEN
├─ state corrupt → 503 STATE_UNAVAILABLE "OpenBox library data needs recovery…"
├─ handler returns ApiError → its status + stable code (GAME_NOT_FOUND, MEDIA_NOT_FOUND, …)
└─ unhandled exception → 500 INTERNAL_ERROR "Unexpected server error. Copy the diagnostic log…"
Most structured error responses carry a stable code and a request_id. The request id is a short per-request token that also appears in the diagnostic log, so a screenshot of an error banner can be correlated with the log line.
Since 2.0, every error response is an application/problem+json (RFC 9457) document carrying type, title, status, detail, code, retryable, request_id, and instance; the error field is kept as a duplicate of detail for one compatibility cycle. The payload examples in the table below show the fields older integrations read; the full document adds the problem-details members on top.
Handlers return a typed ApiError; validation failures are 400 with a readable detail, and state errors are mapped before the handler runs (409 for schema-too-old, future, or frozen; 503 for corrupt state). An unhandled failure is logged and returned as 500 with a request_id.
This is why almost every operation failure you hit through the API is a 400 with a readable, specific message, and why a 500 is genuinely "something the developers need to see," not a normal error path.
Bodies
- POST bodies must be JSON. Bodies over 65,536 bytes are rejected with
"Request is too large."; truncated bodies with"Request body was truncated.". - The body must decode to a JSON object;
[],null,"text", and malformed JSON return400. - GET requests take parameters from the query string; repeated keys are parsed as lists.
Response headers
JSON responses are served with Cache-Control: no-store, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, and a restrictive Content-Security-Policy. Rate-limited auth returns 429 with Retry-After. The request timeout is 30 seconds, SSE events are capped at 64 KiB and 16 subscribers, and the webhook envelope at 64 KiB. Media files are served with immutable cache headers, ETag, Last-Modified, Accept-Ranges, and byte-range (206/416) support; theme.css revalidates with public, max-age=0, must-revalidate and ETag.
Common errors
| Status | Envelope | When |
|---|---|---|
| 403 | {"error":"Unauthorized"} | Missing or wrong token on any protected route, including /api/v2/native/* |
| 403 | {"error":"Request host is not allowed.","code":"BAD_HOST","request_id":"…"} | Host header mismatch or foreign network host rejected |
| 429 | {"error":"Too many authentication failures. Try again later.","code":"RATE_LIMITED","retry_after":n} | Rate limited after repeated auth failures (Retry-After header sent) |
| 400 | {"error": "<message>", "code": "BAD_REQUEST", "request_id": "…"} | Validation failures, missing prerequisites surfaced by handlers, provider errors, unknown queue/notification actions, malformed payloads |
| 404 | {"error":"Not found","code":"ROUTE_NOT_FOUND","request_id":"…"} | Unknown route after authentication. An unauthenticated unknown route returns 403. |
| 404 | GAME_NOT_FOUND / MEDIA_NOT_FOUND / DOCUMENT_NOT_FOUND / PLATFORM_DOCUMENT_NOT_FOUND / BADGE_NOT_FOUND | Lookups that miss |
| 409 | {"error":"Download the LaunchBox metadata database first.","code":"CONFLICT","request_id":"…"} | Metadata routes that need the LaunchBox database (for example GET /api/v2/metadata/search) before it is downloaded |
| 503 | {"error":"OpenBox library data needs recovery before this operation can continue.","code":"STATE_UNAVAILABLE"} | Corrupt state file |
| 503 | {"error":"Server is busy. Close an unused tab and try again.","code":"SSE_BUSY","retry_after":5}, with Retry-After: 5 | GET /api/v2/events already has its 16 subscribers |
| 500 | {"error":"Unexpected server error. Copy the diagnostic log from Settings and include it in your report.","code":"INTERNAL_ERROR"} | Unhandled exception |
Versioned surface
- Public v2 contract (
/api/v2/*): The stable public API. Every/api/v2/*route is part of the ratcheted contract; 3.0 adds Save Vault, Achievement Trail, Deal Radar, Time Capsules, Milestones, and Backlog Itinerary on API 3.0 changes. The 2.0 and 2.1 transitions are recorded on API 2.0 changes and API 2.1 changes. - Native host channel (
/api/host/*): The authenticated channel the bundled native windows use (launch,resume,shutdown,capabilities). Host requests carryX-OpenBox-API-Version: 2; a mismatched major version is refused409 HOST_API_UNSUPPORTEDbefore any route runs. - Removed surfaces:
/api/v1/*returns410 V1_API_REMOVED; the legacy host names/api/launch,/api/shutdown, and/api/native/capabilitiesreturn410 HOST_CHANNEL_RETIRED; any other unversioned/api/*path with a v2 twin returns410 API_VERSION_REQUIRED.OPENBOX_ENABLE_V1_APIis ignored.
- v2 surface added before 2.0: Modern workflows introduced in v1.7.0 through 1.19.1, now part of the public contract:
- Setup Center:
POST /api/v2/setup/preview,GET /api/v2/setup/preview,GET /api/v2/setup/preview/items,POST /api/v2/setup/preview/decisions,POST /api/v2/setup/preview/revalidate,POST /api/v2/setup/commit,GET /api/v2/setup/summary - Launch Doctor:
POST /api/v2/launch/preflight,POST /api/v2/launch/preflight/batch - Emulator Registry:
GET /api/v2/emulators/registry(with?health=1for BIOS/firmware/core status) - Metadata Matches:
POST /api/v2/metadata/matches/preview,GET /api/v2/metadata/matches/preview,GET /api/v2/metadata/matches/items,POST /api/v2/metadata/matches/decisions,POST /api/v2/metadata/matches/apply - Durable Operations:
GET /api/v2/jobs,GET /api/v2/jobs/items,POST /api/v2/jobs/cancel,POST /api/v2/jobs/retry,POST /api/v2/jobs/resume - Play Insights:
GET /api/v2/insights/summary,GET /api/v2/insights/heatmap - Backup Diff:
GET /api/v2/backup/diff?archive=<name>(v1.7.2) - ScreenScraper:
GET /api/v2/screenscraper/status,GET /api/v2/screenscraper/search,POST /api/v2/screenscraper/test,POST /api/v2/screenscraper/info,POST /api/v2/screenscraper/match(batch, cancellable),POST /api/v2/screenscraper/apply(durable job that downloads media outside the state lock) (v1.8.0) - Library Export:
POST /api/v2/library/export(queues durable job),GET /api/v2/library/export/exports,GET /api/v2/library/export/download(v1.8.0) - Picker (v1.9.0):
POST /api/v2/library/pick(scored recommendations by time, mood, familiarity, players) - Constellation (v1.9.0):
GET /api/v2/library/constellation(capped deterministic nodes/edges) - Wrapped + Timeline + Mastery (v1.9.0):
GET /api/v2/insights/wrapped?year=YYYY,GET /api/v2/history/timeline?days=90,GET /api/v2/insights/mastery - Game Night (v1.9.0):
POST /api/v2/party/queue,GET /api/v2/party/queue,POST /api/v2/party/next - LaunchBox Migration (v1.9.0):
POST /api/v2/import/launchbox/preview,POST /api/v2/import/launchbox/apply - Manual Entries (v1.9.0; update and convert in v1.10.0):
POST /api/v2/library/manual-entry,POST /api/v2/library/manual-entry/update,POST /api/v2/library/manual-entry/convert - Causal Catalog Sync (publish and pull from v1.9.0; preview and apply from v1.10.0):
POST /api/v2/library/sync/preview,POST /api/v2/library/sync/apply, andPOST /api/v2/library/sync/publishwith{"protocol":"v3"}. Preview is read-only; apply requires the reviewed plan and creates a recovery backup; publish acknowledges the local outbox after a stale-state check. The old full-library publish payload andPOST /api/v2/library/sync/pullreturn503 LIBRARY_SYNC_UNAVAILABLEbefore mutation. - SQLite Search (v1.9.0):
GET /api/v2/library/search?q=&limit=(FTS5 or LIKE fallback;OPENBOX_ENABLE_SQLITE_READ=1opts in, and the read model self-enables at 5,000+ games since v1.12.0 unless opted out) - Quick Resume, Moments, and session context (v1.11.0):
GET /api/v2/resume/status,POST /api/v2/resume,POST /api/v2/resume/discard,GET /api/v2/moments,POST /api/v2/moments,POST /api/v2/moments/resume,POST /api/v2/moments/update,POST /api/v2/moments/delete,GET /api/v2/sessions/recap,GET /api/v2/clips,POST /api/v2/clips/capture,GET /api/v2/reels, andPOST /api/v2/reels/create. Resume is adapter-capability and state-fingerprint aware; clips use an optional OBS replay buffer with a local screenshot fallback; reel creation is a durable local operation. - Memory gallery (v1.11.0):
GET /api/v2/memories,GET /api/v2/memories/status,GET /api/v2/memories/media, andPOST /api/v2/memories/import. Import is opt-in and queued; the read routes never scan configured folders themselves. - Time Machine and query grammar (v1.11.0):
GET /api/v2/library/time-machine/events,GET /api/v2/library/time-machine/as-of,POST /api/v2/library/time-machine/revert, andPOST /api/v2/library/query/parse. Time Machine is journal-backed and bounded; revert previews must be reviewed and applied with a currentbase_token. Query parsing is read-only and deterministic. - Backlog Radio (v1.11.0):
GET /api/v2/insights/radio,POST /api/v2/insights/radio/refresh,GET /api/v2/insights/radar, andPOST /api/v2/insights/radar/park. Recommendations use local history and return explanations; there is no remote recommendation service. - Arcade Room kiosk boundary (v1.11.0):
GET /api/v2/arcade/kiosk/status,POST /api/v2/arcade/kiosk/pin, andPOST /api/v2/arcade/kiosk/verify. The salted PIN is a local Museum convenience boundary, not API authentication or security. - Household (v1.11.0):
GET /api/v2/household,GET /api/v2/household/leaderboard,POST /api/v2/household/member,POST /api/v2/household/challenge,POST /api/v2/household/challenge/result,POST /api/v2/household/share,POST /api/v2/household/merge,POST /api/v2/household/record,POST /api/v2/household/sync/publish, andPOST /api/v2/household/sync/pull. Records are local-first and sync only through a configured mounted folder; stats sharing is opt-in. - Steam Bridge and ES-DE migration (v1.11.0):
GET /api/v2/steambridge/status,POST /api/v2/steambridge/preview,POST /api/v2/steambridge/apply,POST /api/v2/steambridge/remove/preview,POST /api/v2/steambridge/remove,POST /api/v2/import/esde/preview, andPOST /api/v2/import/esde/apply. Both workflows are preview/apply based and reject stale source or reviewed plans before mutation. - SteamGridDB artwork (v1.11.0):
GET /api/v2/steamgrid/status,GET /api/v2/steamgrid/search,POST /api/v2/steamgrid/test,POST /api/v2/steamgrid/info,POST /api/v2/steamgrid/apply, andPOST /api/v2/steamgrid/match. The provider requiresSTEAMGRIDDB_API_KEY, is optional, and returns durable job IDs for apply and bulk match. - OpenBox launcher trophies (v1.11.0):
GET /api/v2/insights/trophiesandPOST /api/v2/insights/trophies/evaluate. Awards are deterministic over local library/history data and are separate from RetroAchievements. - Smart collections (v1.12.0):
GET /api/v2/collections,POST /api/v2/collections, andPOST /api/v2/collections/delete. A collection stores the query, not a snapshot, so membership re-evaluates at read time. - Game Story (v1.12.0):
GET /api/v2/story?game_id=— a read-only deterministic timeline per game over the game record, session journal, and Moments. - Per-game launch options and scheduled backups (v1.12.0):
launch_envandlaunch_confirmfields on the game record, plus the opt-in weekly automatic backup settingsbackup_auto_enabled/backup_auto_keep/last_auto_backup. - Game DNA search (v1.14.0):
GET /api/v2/library/dna/status,POST /api/v2/library/dna/search(BM25 + 151-concept lexicon, title fallback when degraded), andPOST /api/v2/library/dna/index/rebuild(durable job). - Library health score (v1.14.0):
GET /api/v2/library/health,POST /api/v2/library/health/scan,GET /api/v2/library/health/issues,POST /api/v2/library/health/fix(preview-then-execute with a preview token; theartworkdimension is the Artwork Doctor), andPOST /api/v2/library/health/undo(journal-backed undo). - Backlog management (v1.14.0):
POST /api/v2/library/progress/set,POST /api/v2/library/rating/set,POST /api/v2/library/notes/add|update|delete, andPOST /api/v2/library/playtime/log|update|delete. - Duplicate merge and missing-file repair (v1.14.0):
GET /api/v2/library/duplicates,POST /api/v2/library/duplicates/preview|merge,GET /api/v2/library/repair, andPOST /api/v2/library/repair/preview|apply. Both are preview/apply based and reversible. - Effortless metadata (v1.14.0):
GET /api/v2/metadata/media-candidates(thumbnail chooser),GET/POST /api/v2/metadata/scrape-settings(auto-scrape master toggle plus provider opt-ins), andPOST /api/v2/metadata/auto-scrape(queues match + media jobs for an import batch). - Plugins 2.0 (v1.14.0):
GET /api/v2/plugins/catalog,GET /api/v2/plugins/commands,POST /api/v2/plugins/command,GET/POST /api/v2/plugins/trust(checksum-bound),POST /api/v2/plugins/permissions, andGET/POST /api/v2/plugins/settings. - Launch Readiness (v1.16.0):
POST /api/v2/launch/audit/scan(cancellable whole-library job),GET /api/v2/launch/audit(cached report: ready/warning/blocked totals, one row per root cause, paginated members via?group=), reusing the Launch Doctor's cause codes unchanged. Deep mode is opt-in and the report lives incache/launch_audit.json, never inlibrary.json. - Launch badges and scoped refresh (v1.16.1):
GET /api/v2/launch/audit/status(per-gameblocked/warningfor the grid, empty when the report is stale) andPOST /api/v2/launch/audit/refresh(re-check one group's games in-request; refuses a report that no longer matches the library). - Flatpak folder grants (v1.16.1):
POST /api/v2/launch/grantandPOST /api/v2/launch/grant/undogrant and remove a read-onlyflatpak override --user --filesystem=<folder>:roentry, replacing a reinstall prompt that could not grant access. - Per-game RetroArch core (v1.16.1):
GET /api/v2/launch/cores(installed cores) andPOST /api/v2/launch/core(bind one to a game; an empty core restores the definition default). - Game Night decks (v1.17.0):
GET/POST /api/v2/party/deckslist and upsert a named deck (players, minutes, filter query, capped at 20), andPOST /api/v2/party/decks/deleteremoves one by name. The existing party queue route accepts an eight-character seed so the same seed and library reproduce the same draw. - Native Windows storefront imports (v1.17.0):
POST /api/v2/import/gog,POST /api/v2/import/ea, andPOST /api/v2/import/ubisoftdiscover installed games from the launchers' registry entries and manifests. Discovery is offline and read-only; merging is by stable provider id. On hosts other than Windows the routes return400since 1.19.1. - Platform, media, saves, and plugin services (v1.18.0):
POST /api/v2/platform/renameandPOST /api/v2/platform/delete;GET /api/v2/media/queuewithPOST /api/v2/media/queue/pause|resume|cancel|retryandPOST /api/v2/media/cache/cleanup;GET /api/v2/saves/manifestandPOST /api/v2/saves/restore/preview;POST /api/v2/resume/slot;POST /api/v2/achievements/refreshandPOST /api/v2/achievements/override;GET /api/v2/highscores/table;POST /api/v2/bulk/find-replace;GET/POST /api/v2/plugins/credentials,GET/POST /api/v2/plugins/data,GET /api/v2/plugin-stats,POST /api/v2/plugin-stats/refresh, andPOST /api/v2/plugins/repair. - Storefronts, credentials, imports, and native surfaces (v1.18.0):
GET /api/v2/storefronts,GET /api/v2/storefront/status,POST /api/v2/storefront/scan,POST /api/v2/storefronts/plugin/catalog, andPOST /api/v2/storefronts/plugin/import;GET/POST /api/v2/integration-tokens,POST /api/v2/integration-tokens/remove,GET/POST /api/v2/integrations/steam,POST /api/v2/integrations/steam/test, andPOST /api/v2/integrations/steam/refresh;POST /api/v2/import/pico8,POST /api/v2/import/msu1, andPOST /api/v2/import/whdload;GET/POST /api/v2/emulators/settings;GET /api/v2/netplay/lobby;GET /api/v2/native/battery;POST /api/v2/steam/actionandPOST /api/v2/game/store-action; andPOST /api/v2/metadata/candidates/apply. - Presentation assets (v1.18.0):
GET /api/v2/bigbox/startup-video,GET/POST /api/v2/platform/videos,GET /api/v2/platform/video,GET /api/v2/theme-sounds, andGET /api/v2/theme-asset.
- Setup Center:
See API 1.11 additions, API 1.12 additions, API 1.14 additions, API 1.16 additions, API 1.17 additions, API 1.18 additions, and API 1.19 changes for request bodies, response examples, optional-tool caveats, and stale-plan handling.
- Locale files (public, no auth):
GET /locales/{en,es,de,fr,pt}.json— serves JSON locale files for the i18n system (v1.7.2)
Machine-Readable Error Codes
| Code | Meaning |
|---|---|
PREVIEW_NOT_FOUND / PREVIEW_STALE / PREVIEW_EXPIRED / PREVIEW_LIBRARY_CHANGED | Setup preview session expired, stale, or invalidated by a library change |
PREVIEW_LIMIT_EXCEEDED / PREVIEW_ENTRY_LIMIT_EXCEEDED | Preview exceeds the entry or payload limit |
UNRESOLVED_CANDIDATES | Commit attempted while ambiguous candidates remain unresolved |
EMULATOR_REQUIRED / AMBIGUOUS_PLATFORM / BIOS_MISSING | Launch Doctor preflight check codes (returned in checks, not as HTTP error codes) |
JOB_STATE_CONFLICT | Durable operation scheduling or state conflict |
JOB_NOT_CANCELLABLE / JOB_NOT_RESUMABLE | Operation transition disallowed in current state |
LIBRARY_SYNC_UNAVAILABLE | Legacy full-library publish/pull is disabled; use the v3 preview/apply/publish catalog transport |
SYNC_NOT_ENABLED | Library synchronization must be explicitly enabled before catalog operations |
SYNC_INVALID / SYNC_PREVIEW_STALE / SYNC_PUBLISH_STALE | Catalog event validation failed or the local state changed since preview/publication began |
Limits that apply across routes
| Limit | Value |
|---|---|
| Request body | 65,536 bytes |
| Socket timeout | 30 seconds |
| Playlist members | 100,000 per playlist |
History returned by /api/v2/history | limit clamped to 1..500, default 100 |
| Webhook configs | 32 |
| Watch folders | 50 |
The shared read endpoint
/api/v2/libraryAuthX-OpenBox-Token: TOKENThe full public library projection, cached until the library file, media epoch, or plugin epoch changes.
Returns games, playlists, filter_presets, ra_configured, settings, discovery, and media_epoch. Each game includes every editable field (with "" defaults) plus computed flags: id (numeric index), game_id (stable), favorite, hidden, last_played, play_count, playtime_seconds, path_exists, has_cover/has_background/…, has_saves, has_documents, has_achievements, tags, custom_fields, store_catalog, store_installed, owned, and more.
In safe mode the library hook is skipped; otherwise plugin library hooks can transform the games list before it is returned (cached for 30 seconds, invalidated on state changes).
Security notes
- Treat
server.tokenlike a password: it grants full read/write access to the library, media, settings, and destructive operations. - The API can read any local file path referenced by library entries (media, documents, saves). Keep local paths and exported library data private.
- Never log tokens or paste library exports into issues. The diagnostic log redacts credentials.
See How OpenBoxGL works for the server, state store, and lifecycle, and Configuration for the data directory.