{"openapi":"3.1.0","info":{"title":"Brace Down API","version":"v1 (20261119-38898abdeb6d)","description":"Unified game API convention v1. Real-time: WebSocket at /api/v1/ws, subprotocol bracedown.v1.msgpack, envelope {t, seq, d}; see docs/realtime-protocol.md."},"servers":[{"url":"/"}],"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"Meta":{"type":"object","required":["build","api","proto","minClient","serverTime","features"],"properties":{"build":{"type":"string"},"api":{"type":"string"},"proto":{"type":"integer"},"minClient":{"type":"string"},"serverTime":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}}}},"GuestRequest":{"type":"object","properties":{"client":{"anyOf":[{"const":"web","type":"string"},{"const":"portal","type":"string"},{"const":"native","type":"string"}]}}},"AuthResponse":{"type":"object","required":["playerId","handle","accessToken","accessExpiresIn","refreshToken"],"properties":{"playerId":{"type":"string"},"handle":{"type":"string"},"accessToken":{"type":"string"},"accessExpiresIn":{"type":"integer"},"refreshToken":{"description":"Only returned to portal/native clients; web gets an httpOnly cookie.","anyOf":[{"type":"string"},{"type":"null"}]}}},"RefreshRequest":{"type":"object","properties":{"refreshToken":{"description":"Portal/native only; web sends the cookie.","type":"string"},"client":{"type":"string"}}},"SandboxJoinRequest":{"type":"object","properties":{"seed":{"minimum":1,"maximum":2147483647,"type":"integer"}}},"SandboxJoinResponse":{"type":"object","required":["roomId","ticket","rt","resumeToken"],"properties":{"roomId":{"type":"string"},"ticket":{"description":"Single use, ~30 s. Send in the first hello frame.","type":"string"},"rt":{"description":"WebSocket path, subprotocol bracedown.v1.msgpack","type":"string"},"resumeToken":{"type":"string"}}},"SandboxStats":{"type":"object","required":["edits","solverMsAvg","solverMsMax","bytesPerOpMsgAvg","opMessages","collapses","cellsFallen","snapshotBytes","cells","stressLimit"],"properties":{"edits":{"type":"integer"},"solverMsAvg":{"type":"number"},"solverMsMax":{"type":"number"},"bytesPerOpMsgAvg":{"type":"number"},"opMessages":{"type":"integer"},"collapses":{"type":"integer"},"cellsFallen":{"type":"integer"},"snapshotBytes":{"type":"integer"},"cells":{"type":"integer"},"stressLimit":{"type":"integer"}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v1/meta":{"get":{"summary":"Build, API/protocol versions, min client, server time, features","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meta"}}}}}}},"/api/v1/healthz":{"get":{"summary":"Liveness","responses":{"200":{"description":"ok"}}}},"/api/v1/openapi.json":{"get":{"summary":"This document","responses":{"200":{"description":"OpenAPI 3.1"}}}},"/api/v1/auth/guest":{"post":{"summary":"Create a guest player and session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/auth/refresh":{"post":{"summary":"Rotate the refresh token, get a new access token","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/auth/logout":{"post":{"summary":"Revoke this session","security":[{"bearer":[]}],"responses":{"204":{"description":"revoked"}}}},"/api/v1/sandbox/join":{"post":{"summary":"Get (or resume) your sandbox room and a real-time join ticket. Accepts Idempotency-Key.","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxJoinRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxJoinResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sandbox/stats":{"get":{"summary":"Solver and network cost for your room (PoC metrics)","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxStats"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mines/{hash}.bin":{"get":{"summary":"Immutable mine snapshot (RLE cells+flags). ETag = hash.","parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"application/octet-stream"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}