{"openapi":"3.1.0","info":{"title":"MUPLAGA API","version":"1.0.0","description":"Gemeinsame REST-API für Website, iOS- und Android-App. Website: Cookie-Sitzung (mpg_session). Apps: Bearer-Token aus /auth/login mit client=ios|android. Gäste: Cookie mpg_guest bzw. Header X-Guest-Key (wird beim ersten Spielstart erzeugt und im Response-Header X-Guest-Key zurückgegeben). Alle Fehler haben das Format {\"error\":{\"code\",\"message\",\"details\"}}. Zustandsändernde Cookie-Anfragen müssen von der eigenen Origin stammen (CSRF-Schutz).\n"},"servers":[{"url":"https://muplaga.com/api/v1"}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"mpg_session"},"bearerAuth":{"type":"http","scheme":"bearer"},"guestKey":{"type":"apiKey","in":"header","name":"X-Guest-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_FAILED","INVALID_JSON","AUTH_REQUIRED","AUTH_INVALID_CREDENTIALS","AUTH_TOKEN_INVALID","EMAIL_NOT_VERIFIED","FORBIDDEN","CSRF_REJECTED","NOT_FOUND","METHOD_NOT_ALLOWED","DISPLAY_NAME_TAKEN","PROGRESS_CONFLICT","SESSION_COMPLETED","ASSIST_NOT_ALLOWED","CHALLENGE_FULL","CHALLENGE_CLOSED","RATE_LIMITED","REGISTRATION_CLOSED","TOKEN_INVALID","NOT_IMPLEMENTED","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{}}}}},"User":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":"string"},"locale":{"type":"string","enum":["de","en"]},"createdAt":{"type":"string","format":"date-time"}}},"Session":{"type":"object","properties":{"token":{"type":"string","description":"Nur für Apps (client=ios|android); Website erhält ein Cookie."},"expiresAt":{"type":"string","format":"date-time"}}},"Level":{"type":"object","properties":{"id":{"type":"string","description":"Dauerhafte, nicht erratbare Level-ID"},"game":{"type":"string"},"difficulty":{"type":"string","enum":["leicht","mittel","schwer","experte"]},"difficultyScore":{"type":"integer"},"title":{"type":["string","null"]},"rulesetVersion":{"type":"string"},"generatorVersion":{"type":"string"},"definition":{"type":"object","description":"Sudoku: {grid: 81 Zeichen, 0 = leer}. Die Lösung wird nie ausgeliefert."},"url":{"type":"string"},"daily":{"type":["string","null"]}}},"SudokuState":{"type":"object","required":["values","notes"],"properties":{"values":{"type":"string","pattern":"^[0-9]{81}$"},"notes":{"type":"array","items":{"type":"integer","minimum":0,"maximum":511},"minItems":81,"maxItems":81}}},"GameSession":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["competitive","practice"]},"status":{"type":"string","enum":["active","paused","completed"]},"elapsedMs":{"type":"integer","description":"Serverseitig gemessene Spielzeit"},"paused":{"type":"boolean"},"hintsUsed":{"type":"integer"},"challenge":{"type":["string","null"]},"level":{"$ref":"#/components/schemas/Level"},"progress":{"type":["object","null"],"properties":{"state":{"$ref":"#/components/schemas/SudokuState"},"revision":{"type":"integer"}}},"result":{"$ref":"#/components/schemas/Result"},"personalBestMs":{"type":["integer","null"]}}},"Result":{"type":["object","null"],"properties":{"solved":{"type":"boolean"},"timeMs":{"type":"integer"},"verified":{"type":"boolean","description":"Für Bestenlisten gewertet"},"rejectReason":{"type":["string","null"],"enum":["practice_mode","assists_used","implausibly_fast","clock_mismatch",null]},"completedAt":{"type":"string","format":"date-time"}}},"Board":{"type":"object","properties":{"board":{"type":"string"},"total":{"type":"integer"},"entries":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"name":{"type":"string"},"timeMs":{"type":"integer"},"achievedAt":{"type":"string"},"isYou":{"type":"boolean"}}}},"you":{"type":["object","null"],"properties":{"rank":{"type":"integer"},"scoreMs":{"type":"integer"}}}}},"Challenge":{"type":"object","properties":{"code":{"type":"string"},"url":{"type":"string"},"title":{"type":["string","null"]},"status":{"type":"string","enum":["open","closed"]},"creator":{"type":"string"},"level":{"$ref":"#/components/schemas/Level"},"isCreator":{"type":"boolean"},"isParticipant":{"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string","enum":["creator","participant"]},"status":{"type":"string","enum":["pending","finished","unranked"]},"timeMs":{"type":["integer","null"]},"rank":{"type":["integer","null"]}}}}}}},"responses":{"Error":{"description":"Fehler","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health-Check (DB-Verbindung, Version)","security":[],"responses":{"200":{"description":"OK"}}}},"/auth/register":{"post":{"tags":["Auth"],"summary":"Registrierung; antwortet immer 202 (keine Konto-Enumeration), Bestätigungsmail folgt","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password","displayName"],"properties":{"email":{"type":"string"},"password":{"type":"string","minLength":10},"displayName":{"type":"string","minLength":3,"maxLength":20},"locale":{"type":"string"}}}}}},"responses":{"202":{"description":"check_email"},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/auth/verify":{"post":{"tags":["Auth"],"summary":"E-Mail-Adresse mit Token aus der Mail bestätigen","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"}}}},"/auth/verify/resend":{"post":{"tags":["Auth"],"summary":"Bestätigungsmail erneut senden (immer 202)","security":[],"responses":{"202":{"description":"OK"}}}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Anmeldung; übernimmt Gast-Spielstände (Cookie/X-Guest-Key) ins Konto","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"},"client":{"type":"string","enum":["web","ios","android"]},"deviceLabel":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"claimedSessions":{"type":"integer"},"session":{"$ref":"#/components/schemas/Session"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Abmelden (beendet die aktuelle Sitzung)","responses":{"200":{"description":"OK"}}}},"/auth/refresh":{"post":{"tags":["Auth"],"summary":"Token rotieren (Apps); altes Token wird ungültig","responses":{"200":{"description":"OK"}}}},"/auth/password/forgot":{"post":{"tags":["Auth"],"summary":"Reset-Link anfordern (immer 202)","security":[],"responses":{"202":{"description":"OK"}}}},"/auth/password/reset":{"post":{"tags":["Auth"],"summary":"Neues Passwort mit Reset-Token setzen; beendet alle Sitzungen","security":[],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"}}}},"/auth/password/change":{"post":{"tags":["Auth"],"summary":"Passwort ändern (aktuelles Passwort nötig); andere Sitzungen werden beendet","responses":{"200":{"description":"OK"}}}},"/auth/external/{provider}":{"post":{"tags":["Auth"],"summary":"Vorbereitet: Sign in with Apple, Google Sign-In, Game Center, Play Games (derzeit 501)","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["apple","google","apple_game_center","google_play_games"]}}],"responses":{"501":{"$ref":"#/components/responses/Error"}}}},"/me":{"get":{"tags":["Konto"],"summary":"Eigenes Profil","responses":{"200":{"description":"OK"}}},"patch":{"tags":["Konto"],"summary":"Anzeigename/Sprache ändern","responses":{"200":{"description":"OK"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Konto"],"summary":"Konto mit allen Daten löschen (Passwort nötig)","responses":{"200":{"description":"OK"}}}},"/me/export":{"get":{"tags":["Konto"],"summary":"Datenexport (JSON) nach Art. 15/20 DSGVO","responses":{"200":{"description":"OK"}}}},"/me/stats":{"get":{"tags":["Konto"],"summary":"Persönliche Statistik, letzte Ergebnisse, Erfolge","responses":{"200":{"description":"OK"}}}},"/me/identities":{"get":{"tags":["Konto"],"summary":"Verknüpfte externe Identitäten (Auth-Anbieter und Gaming-Plattformen)","responses":{"200":{"description":"OK"}}}},"/games":{"get":{"tags":["Spiele"],"summary":"Alle Spiele inkl. angekündigter","security":[],"responses":{"200":{"description":"OK"}}}},"/games/{game}":{"get":{"tags":["Spiele"],"summary":"Spielinfo, Schwierigkeitsgrade, aktuelles Regelwerk","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Error"}}}},"/games/{game}/levels/{id}":{"get":{"tags":["Spiele"],"summary":"Level per dauerhafter ID (ohne Lösung)","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"level":{"$ref":"#/components/schemas/Level"}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/games/{game}/daily":{"get":{"tags":["Spiele"],"summary":"Tagesrätsel (heute oder ?day=JJJJ-MM-TT in der Vergangenheit)","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}},{"name":"day","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/sessions":{"get":{"tags":["Spielstände"],"summary":"Offene Spiele (Konto oder Gast) zum Fortsetzen","security":[{"cookieAuth":[]},{"bearerAuth":[]},{"guestKey":[]}],"responses":{"200":{"description":"OK"}}},"post":{"tags":["Spielstände"],"summary":"Spiel starten (Level-ID, Schwierigkeit, Tagesrätsel oder Challenge); setzt laufendes Spiel auf demselben Level fort","security":[{"cookieAuth":[]},{"bearerAuth":[]},{"guestKey":[]},{}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["game"],"properties":{"game":{"type":"string"},"level":{"type":"string"},"difficulty":{"type":"string"},"daily":{"type":"boolean"},"challenge":{"type":"string"},"mode":{"type":"string","enum":["competitive","practice"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/GameSession"}}}}}}}}},"/sessions/{id}":{"get":{"tags":["Spielstände"],"summary":"Spielstand laden (geräteübergreifend)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Error"}}}},"/sessions/{id}/progress":{"put":{"tags":["Spielstände"],"summary":"Fortschritt speichern; revision muss aktuell sein, sonst 409 PROGRESS_CONFLICT mit aktuellem Stand","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["state","revision"],"properties":{"state":{"$ref":"#/components/schemas/SudokuState"},"revision":{"type":"integer"},"clientElapsedMs":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK"},"409":{"$ref":"#/components/responses/Error"}}}},"/sessions/{id}/pause":{"post":{"tags":["Spielstände"],"summary":"Pause (Serverzeit stoppt)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/sessions/{id}/resume":{"post":{"tags":["Spielstände"],"summary":"Fortsetzen","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/sessions/{id}/hint":{"post":{"tags":["Spielstände"],"summary":"Tipp (nur Übungsmodus)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"409":{"$ref":"#/components/responses/Error"}}}},"/sessions/{id}/check":{"post":{"tags":["Spielstände"],"summary":"Fehlerprüfung gegen die Lösung (nur Übungsmodus)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"409":{"$ref":"#/components/responses/Error"}}}},"/sessions/{id}/submit":{"post":{"tags":["Spielstände"],"summary":"Lösung abgeben; Server prüft Lösung und Zeit; idempotent (ein Ergebnis je Sitzung)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["state"],"properties":{"state":{"$ref":"#/components/schemas/SudokuState"},"clientElapsedMs":{"type":"integer"}}}}}},"responses":{"200":{"description":"solved=false mit reason, oder solved=true mit result"}}}},"/leaderboards/{game}/levels/{id}":{"get":{"tags":["Bestenlisten"],"summary":"Bestenliste eines Levels","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Board"}}}}}}},"/leaderboards/{game}/daily":{"get":{"tags":["Bestenlisten"],"summary":"Tagesrätsel-Bestenliste (?day=)","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}},{"name":"day","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/leaderboards/{game}/difficulty/{difficulty}":{"get":{"tags":["Bestenlisten"],"summary":"Rangliste je Schwierigkeitsgrad (Anzahl Erstlösungen, Bestzeit)","security":[],"parameters":[{"name":"game","in":"path","required":true,"schema":{"type":"string"}},{"name":"difficulty","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/leaderboards/weekly":{"get":{"tags":["Bestenlisten"],"summary":"Meistgelöste Spieler der letzten 7 Tage","security":[],"responses":{"200":{"description":"OK"}}}},"/challenges":{"get":{"tags":["Challenges"],"summary":"Eigene erstellte und angenommene Herausforderungen","responses":{"200":{"description":"OK"}}},"post":{"tags":["Challenges"],"summary":"Herausforderung aus einem Level erstellen","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["level"],"properties":{"level":{"type":"string"},"title":{"type":"string"},"maxParticipants":{"type":"integer","minimum":2,"maximum":100}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"challenge":{"$ref":"#/components/schemas/Challenge"}}}}}}}}},"/challenges/{code}":{"get":{"tags":["Challenges"],"summary":"Herausforderung mit Teilnehmenden und Ergebnissen","security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Challenges"],"summary":"Link widerrufen (nur erstellende Person)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"403":{"$ref":"#/components/responses/Error"}}}},"/challenges/{code}/join":{"post":{"tags":["Challenges"],"summary":"Herausforderung annehmen","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/challenges/{code}/close":{"post":{"tags":["Challenges"],"summary":"Herausforderung beenden (nur erstellende Person)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}