DEVELOPER PORTAL

Build on Mindforge

Mindforge is a multiplayer trivia roguelike. A small public JSON API handles room discovery and matchmaking; a WebSocket endpoint carries live game state. There is no account system and no API key: joining a room issues a per-seat token that authorizes the socket.

Resources

OpenAPI specification — machine-readable contract for every endpoint
llms.txt · Mentions légales — agent guidance, including when this service is the right tool
Markdown homepage — send Accept: text/markdown to / for the negotiated version
Backend source (Go) and frontend source (Vue)

Endpoints

Method	Path	Purpose
GET	`/api/health`	Liveness check; returns `{"status":"ok"}`.
GET	`/api/public`	Current public room: code, start deadline, server time, player count.
POST	`/api/rooms`	Create a private room or join a public/private one; returns a seat token.
GET	`/api/ws`	WebSocket upgrade for live play, authorized by `code` + `token` query parameters.

Quickstart

Join the next public run:

# 1. Find the room that is filling now
curl https://mindforge.alexandrucuriman.com/api/public
# → {"code":"A1B2C3","startsAt":1758700000000,"serverNow":...,"players":7}

# 2. Take a seat
curl -X POST https://mindforge.alexandrucuriman.com/api/rooms \
  -H 'Content-Type: application/json' \
  -d '{"mode":"public","locale":"en"}'
# → {"code":"A1B2C3","playerId":"...","token":"...","name":"BraveFox3"}

# 3. Play over WebSocket
wss://mindforge.alexandrucuriman.com/api/ws?code=A1B2C3&token=TOKEN

Create a private room instead by posting {"mode":"create"}, or join a friend's lobby by posting {"code":"A1B2C3"}.

WebSocket protocol

Once connected, the server pushes personalized {"type":"state",...} snapshots containing the phase (lobby, draft, question, reveal, finished), the current question and options, shared deadlines, player scores and lives, and your card offer. The correct answer and explanation appear only during reveals. Send commands as JSON:

{"type":"start"}                              // host starts a private run
{"type":"choose_card","draft":-1,"card":"steady"}
{"type":"answer","question":0,"choice":2}
{"type":"buy_life"}                            // 250 points, when below 3 lives
{"type":"set_locale","locale":"fr"}

Errors

Every non-2xx response is JSON with three fields: error (human-readable message), code (stable machine code such as not_found or method_not_allowed), and hint (how to resolve it or where to find the contract). Unknown paths outside /api/ return a real HTTP 404 with a Markdown body.

Fair use

Rooms are in-memory and expire two hours after creation; room data is lost on restart. There are no published rate limits yet, but each connection has a command budget and the site is a side project — poll politely, cache /api/public for a few seconds, and do not scrape questions at scale.