API overview
Where the endpoints live, how they are authenticated, and which ones RomM calls versus the room UI.
Every endpoint lives under the SUBFOLDER prefix, so with the default the
API root is /streaming/api/. The examples on these pages talk to a container
directly on its HTTPS port; behind a reverse proxy substitute RomM's origin.
Authentication
BROKER_SECRET is a shared secret between RomM and the container. When it is
set, the lifecycle endpoints require it in the X-Broker-Secret header and
answer 403 otherwise. When it is unset nothing is checked, which is only
sensible on a LAN you control.
Endpoints fall into three groups:
| Group | Caller | Auth |
|---|---|---|
| Lifecycle: activate, join, swap-disc | RomM's backend | X-Broker-Secret |
| State and archive transfer: save-state, load-state, state-file, state-screenshot, imports, exports, memory card | RomM's backend | X-Broker-Secret |
| Host actions: invite, exit | the room UI | the controller token as ?token=; exit also accepts the secret |
| Room: context, the collab websocket | the room UI | a personal token in the URL |
| Status and health | anyone | none |
The room UI never holds the secret. Its exit and invite buttons carry the controller token instead, which is why exit accepts either.
Endpoints
| Method | Path | Page |
|---|---|---|
POST | /api/session/activate | Launch a game |
POST | /api/session/swap-disc | Launch a game |
POST | /api/session/join | Users and invites |
POST | /api/session/invite | Users and invites |
POST | /api/session/save-state | Save states |
POST | /api/session/load-state | Save states |
GET / PUT | /api/session/state-file | Save states |
GET | /api/session/state-screenshot | Save states |
POST | /api/session/exit | Exit |
PUT | /api/session/imports/{name}.zip | Save archives |
GET / DELETE | /api/session/exports[/{name}.zip] | Save archives |
GET / PUT | /api/session/memory-card | Save archives |
GET | /api/session/status | Status |
GET | /api/health | Status |
The request and response models are documented in the
Python reference, and a running broker serves
its own OpenAPI schema at <SUBFOLDER>/openapi.json with the interactive
explorer at <SUBFOLDER>/docs.
Conventions
- Status codes carry meaning.
409is "there is no session" (or "there already is one" on activate).400is "the running emulator cannot do that", for example a state route on an emulator without save states.413is a body over a configured ceiling.422is a payload the broker could not act on. - A
"failed"status is a real answer, not an error. Save and load reportfailedwhen the emulator did not acknowledge, or the slot held no state. - Slots resolve to the emulator's working slot. RomM is the library of states, so each emulator works in exactly one slot and echoes the slot it actually used. Whatever slot a request names, the response says which one it landed in.