// OPENBOX DOCS
REST API
Use the local authenticated HTTP API for automation.
The app exposes a local REST API for automation and third-party tooling. The Rust server (openbox-server) binds to loopback only and requires a per-launch token on every request. The public surface is /api/v2/*; the native windows use /api/host/*. Unversioned /api/* paths were retired in 2.1 and /api/v1 was removed in 2.1. This page is the index; each operation group has its own reference page, and How OpenBoxGL works explains the server, the error contract, and the lifecycle.
Quickstart
Find your token and port, then call any route with the X-OpenBox-Token header:
TOKEN=$(cat ~/.local/share/openbox-game-launcher/server.token)
PORT=$(cat ~/.local/share/openbox-game-launcher/server.port)
# List the whole library
curl -s -H "X-OpenBox-Token: $TOKEN" http://127.0.0.1:$PORT/api/v2/library | jq '.games | length'
# Launch a game by stable id
curl -s -X POST -H "X-OpenBox-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": "GAME_ID"}' \
http://127.0.0.1:$PORT/api/v2/launch
# Toggle a favorite
curl -s -X POST -H "X-OpenBox-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": "GAME_ID"}' \
http://127.0.0.1:$PORT/api/v2/favorite
Replace GAME_ID with a real game-<hex> id from /api/v2/library. The token and port live only while the app is running; both files are deleted when the server stops.
Server and transport
- The API listens at
http://127.0.0.1:SERVER_PORTon a random port chosen at startup. The port and token are written toserver.portandserver.tokeninside the data directory and deleted when the server stops. - OpenBoxGL does not terminate HTTPS. The API is designed for the local host. If you expose it beyond the machine, put a trusted reverse proxy in front and understand the trust boundary first.
- Requests time out after 30 seconds at the socket level.
- JSON request bodies are limited to 65,536 bytes. A larger body returns HTTP 400 with a problem document whose detail is "Request is too large.".
Authentication
Every route except the static UI, locale JSON, and other explicitly public assets requires a token. Send it as a header:
X-OpenBox-Token: TOKEN
The query parameter token=TOKEN is also accepted but can leak through browser history, referrer logs, and proxy logs. Prefer the header in anything you write. The app scrubs ?token= from history immediately (history.replaceState) and never logs the token-bearing URL; logs use the token-free http://127.0.0.1:PORT/. The token is compared in constant time. Authentication runs before host-version checks, retired-route guards, and route resolution, so an unknown route without a token returns 403, not 404. A missing or wrong token returns 403 with {"error":"Unauthorized"}. Ten failures in 60 seconds per IP return 429 with code: "RATE_LIMITED" and a Retry-After header; a correct token clears the bucket.
Response envelope
Most API handlers return JSON objects. Since 2.0 every error is served as application/problem+json (RFC 9457) carrying type, title, status, detail, a stable code, retryable, request_id, and instance; error is kept as a duplicate of detail for one compatibility cycle. The payloads below name the fields integrations read today. Public assets, media/download endpoints, and Server-Sent Events can return bytes or streams instead of JSON. The versioned route pages document the response shape for each operation.
| Status | Meaning |
|---|---|
200 | Success |
202 | Accepted; a background job was started (metadata sync, media bulk, emulator install/update, Gameyfin install) |
304 | Not modified (conditional media and theme requests) |
400 | Validation error; the error field names the exact problem (absolute paths are sanitized: the server log keeps the full path, the client receives the prefix before the path) |
403 | {"error":"Unauthorized"}; missing or wrong token on a known protected route |
429 | {"error":"Too many authentication failures. Try again later.", "code":"RATE_LIMITED"}; 10 auth failures in 60 seconds per IP, with Retry-After |
404 | {"error":"Not found"} or a route-specific error for unknown routes or missing games/media/documents, after authentication |
409 | Required local prerequisite is missing (for example, the metadata database has not been downloaded) |
416 | Invalid byte range on media |
503 | {"error":"OpenBox library data needs recovery before this operation can continue."} when the state file is corrupt |
500 | {"error":"Unexpected server error. Copy the diagnostic log from Settings and include it in your report."} |
Handlers return a typed ApiError with a status and stable code; validation failures surface as 400 with a readable detail. A corrupt or too-old state file returns 409 STATE_SCHEMA_TOO_OLD / STATE_FUTURE_VERSION or 503 STATE_UNAVAILABLE before the handler runs. An unhandled failure is a 500 with a logged exception and a request_id.
Route groups
Each group has its own reference page with per-endpoint cards.
Security notes
- Keep exported library data and local paths sensitive. The API can read game paths, media files, documents, and the diagnostic log.
- Secrets (webhook secrets, Gameyfin password, RetroAchievements and EmuMovies credentials) are never returned: credential-bearing settings expose
*_setboolean flags instead, and the diagnostic log redacts tokens, passwords, and API keys. - Restore, deletion, and cleanup operations are destructive by design. They validate archive paths, reject symlinks, and refuse to run while games are running where the operation says so.
Examples
List the library with the header token:
curl -H "X-OpenBox-Token: $TOKEN" http://127.0.0.1:$PORT/api/v2/library
Launch a game by stable id:
curl -X POST -H "X-OpenBox-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"game_id": "GAME_ID"}' \
http://127.0.0.1:$PORT/api/v2/launch
Where $TOKEN and the port come from the running server (cat ~/.local/share/openbox-game-launcher/server.token). On Windows the data directory is %LOCALAPPDATA%\openbox-game-launcher, and on macOS it is ~/Library/Application Support/openbox-game-launcher. See Configuration for the data directory and the application repository for the current route contract (api_contracts.json, mirrored by docs/openapi.json).