Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Games

Games libraries (2026-10-05): starting a game in the browser with the EmulatorJS the owner added to the server — Collectoh brings no emulator, BIOS or game — and the emulator’s status for the admin.

Paths are relative to /api/v1 on your server.

GET/games/{id}/media#

The manual and the video kept with a game

Looked for around the game’s file where front-ends keep them: beside it named as it is, in manuals, videos or snaps folders, or in a media folder of those. A manual is a PDF or a comic archive; a video an MP4 or a WebM.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/games/{id}/media/{kind}#

A game’s manual or video

The file itself, with Accept-Ranges.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
kind requiredpath"manual" | "video"
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: the game has nothing of that kind kept with it application/json · ErrorEnvelope
GET/games/{id}/player#

The player page

An HTML page that loads the owner’s EmulatorJS from this server with the game, its platform’s core and its BIOS. Its Content-Security-Policy lets it reach this server and nothing else.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
filequerystring (uuid)
statequerystring (uuid)
  • 200Success. text/html ·
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/games/{id}/plays#

Start a game

Checks the game plays in a browser on this server — its platform has an emulator core, the copy is not a PC program, and the owner has added EmulatorJS in Admin → Games — then records the play (History, Continue) and answers with the player page to open in a frame. fileId picks a copy (a region, a revision); the primary otherwise.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 201Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: the platform does not play in a browser, or no emulator has been added to the server application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no game the caller can see has that id, or it has no such file application/json · ErrorEnvelope
GET/games/{id}/rom/{fileId}/{name}#

The game itself

The copy’s file, with Accept-Ranges; a disc set (a CUE and its BINs, a GDI and its tracks) as one stored zip, since the emulator is handed one file. name is the file’s name, which some cores read.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
fileId requiredpathstring (uuid)
name requiredpathstring
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. MEDIA_FILE_MISSING: the file, or a part its disc names, is not there application/json · ErrorEnvelope
GET/games/{id}/saves#

Your saves in a game

The caller’s own, newest first: the moments saved from the pause screen (state) and the game’s own saves (battery, one per copy). kind and file narrow them.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
kindquery"state" | "battery"
filequerystring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/games/{id}/saves#

Keep a save on the server

The body is the save’s bytes, as the emulator wrote them (64 MB at most). kind=state keeps a new moment — past thirty for one game, the oldest goes — and kind=battery writes over the copy’s last game save. file is the copy it was made in, core the emulator core that wrote it. A moment’s picture is sent after, to its own address.

Authorisation
Bearer token or API key · Session cookie
Body
application/octet-stream ·
ParameterInTypeDescription
id requiredpathstring (uuid)
kind requiredquery"state" | "battery"
file requiredquerystring (uuid)
core requiredquerystring
  • 201Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: the body is empty application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no game the caller can see has that id, or it has no such file application/json · ErrorEnvelope
  • 413PAYLOAD_TOO_LARGE: the save is over 64 MB application/json · ErrorEnvelope
PUT/games/{id}/status#

Say where you are with a game

LaunchBox’s progress, the caller’s own: not started (unplayed, want, wont), under way (playing, continuous, paused) or done (beaten, completed, mastered, dropped); null says nothing again. A game’s first play makes it playing unless it is under way or done already. The item’s game include reads it back.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no game the caller can see has that id application/json · ErrorEnvelope
GET/games/bios/{platform}#

A platform’s BIOS

The BIOS file the platform’s core is given, the first of the names it looks for that the owner’s BIOS folder holds.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
platform requiredpathstring
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/games/emulator/{dir}/{file}#

The owner’s emulator, a folder down

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
dir requiredpathstring
file requiredpathstring
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/games/emulator/{dir}/{sub}/{file}#

The owner’s emulator, two folders down

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
dir requiredpathstring
sub requiredpathstring
file requiredpathstring
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/games/emulator/{file}#

The owner’s emulator

A file of the EmulatorJS the owner added, by its path in the folder (loader.js; cores/fceumm-wasm.data and cores/reports/fceumm.json by the two routes below): scripts, WebAssembly, cores, their words. Read-only; nothing outside the folder, and only the kinds of file the player loads.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
file requiredpathstring
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/games/plays/{eventId}/end#

A game was closed

How long it was played, as the app counted it, never more than the time since it started. Another person’s play, or one already ended, is left as it is.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
eventId requiredpathstring (uuid)
  • 204Done; no body.
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/games/saves/{saveId}#

A save’s bytes

For the player to load; only the caller’s own.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
saveId requiredpathstring (uuid)
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: the caller has no save with that id application/json · ErrorEnvelope
DELETE/games/saves/{saveId}#

Delete a save

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
saveId requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: the caller has no save with that id application/json · ErrorEnvelope
GET/games/saves/{saveId}/picture#

The picture of a saved moment

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
saveId requiredpathstring (uuid)
  • 200Success. application/octet-stream ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such save of the caller’s, or it has no picture application/json · ErrorEnvelope
PUT/games/saves/{saveId}/picture#

A picture of a saved moment

A PNG, JPEG or WebP, 4 MB at most, of the screen as the moment was saved.

Authorisation
Bearer token or API key · Session cookie
Body
image/jpeg ·
ParameterInTypeDescription
saveId requiredpathstring (uuid)
  • 204Done; no body.
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: it is not a moment, or the body is not a picture application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: the caller has no save with that id application/json · ErrorEnvelope
GET/games/status#

The emulator and BIOS folders

Whether EmulatorJS is in the folder the owner named, which cores it has, and for each platform whether it plays in a browser here and which BIOS it would be given.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope