{"openapi":"3.1.0","info":{"title":"Lumenpath shared gameplay API","version":"1"},"servers":[{"url":"/api/v1"}],"paths":{"/openapi.json":{"get":{"summary":"Discover the shared human and agent API","operationId":"get__openapi_json","parameters":[],"security":[],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"summary":"Server health and deployed commit","operationId":"get__health","parameters":[],"security":[],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/prepared":{"get":{"summary":"Ready starting worlds by difficulty","operationId":"get__worlds_prepared","parameters":[],"security":[],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds":{"post":{"summary":"Create a private shared world and its first player","operationId":"post__worlds","parameters":[],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"controller":{"type":"string","enum":["human","external","autopilot"],"default":"human"},"seed":{"type":"integer","minimum":-4294967295,"maximum":4294967295},"difficulty":{"type":"string","enum":["normal","medium","hard"],"default":"normal"},"fixture":{"type":"string"}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWorld"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWorld"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWorld"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/import":{"post":{"summary":"Import a legacy browser save into a private world","operationId":"post__worlds_import","parameters":[],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","seed","save"],"properties":{"name":{"type":"string"},"seed":{"type":"integer","minimum":-4294967295,"maximum":4294967295},"save":{"type":"object"}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/{id}":{"get":{"summary":"Read your world and roster","operationId":"get__worlds_id_","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[],"playerId":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldResponse"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldResponse"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldResponse"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/{id}/players":{"post":{"summary":"Join through an invite","operationId":"post__worlds_id_players","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invite","name"],"properties":{"invite":{"type":"string"},"name":{"type":"string"},"controller":{"type":"string","enum":["human","external","autopilot"],"default":"human"}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/{id}/events":{"get":{"summary":"Stream initial state and subsequent state patches","operationId":"get__worlds_id_events","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[],"playerId":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"text/event-stream":{"schema":{"type":"string","description":"data: {view: GameView} initially, then data: {patch: ViewPatch}. Reconnect for a full snapshot."}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"text/event-stream":{"schema":{"type":"string","description":"data: {view: GameView} initially, then data: {patch: ViewPatch}. Reconnect for a full snapshot."}}}},"202":{"description":"Autopilot started.","content":{"text/event-stream":{"schema":{"type":"string","description":"data: {view: GameView} initially, then data: {patch: ViewPatch}. Reconnect for a full snapshot."}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/{id}/reset":{"post":{"summary":"Owner starts the next round for everyone","operationId":"post__worlds_id_reset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[],"playerId":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"seed":{"type":"integer","minimum":-4294967295,"maximum":4294967295},"difficulty":{"type":"string","enum":["normal","medium","hard"],"default":"normal"}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worlds/{id}/retry":{"post":{"summary":"Retry failed district preparation without resetting progress","operationId":"post__worlds_id_retry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[],"playerId":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/observe":{"get":{"summary":"Read a map observation; format=json or text, optional x/y/width/height","operationId":"get__players_id_observe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"enum":["json","text"],"default":"json"}},{"name":"x","in":"query","description":"Supply all four bounds together, or omit all for a 25×25 window around the player.","schema":{"type":"integer","minimum":-1000000,"maximum":1000000}},{"name":"y","in":"query","description":"Supply all four bounds together, or omit all for a 25×25 window around the player.","schema":{"type":"integer","minimum":-1000000,"maximum":1000000}},{"name":"width","in":"query","description":"Supply all four bounds together, or omit all for a 25×25 window around the player.","schema":{"type":"integer","minimum":1,"maximum":120}},{"name":"height","in":"query","description":"Supply all four bounds together, or omit all for a 25×25 window around the player.","schema":{"type":"integer","minimum":1,"maximum":120}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveResponse"}},"text/plain":{"schema":{"type":"string"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveResponse"}},"text/plain":{"schema":{"type":"string"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveResponse"}},"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/act":{"post":{"summary":"Perform one shared gameplay command","operationId":"post__players_id_act","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["request_id","action","params"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"step"},"params":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]}},"required":["direction"],"additionalProperties":false}}},{"type":"object","required":["request_id","action","params"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"dash"},"params":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]}},"required":["direction"],"additionalProperties":false}}},{"type":"object","required":["request_id","action","params"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"hold"},"params":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]},"mode":{"type":"string","enum":["step","dash"],"default":"step"}},"required":["direction"],"additionalProperties":false}}},{"type":"object","required":["request_id","action"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"release"},"params":{"type":"object","properties":{},"required":[],"additionalProperties":false}}},{"type":"object","required":["request_id","action"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"observe"},"params":{"type":"object","properties":{"x":{"type":"integer"},"y":{"type":"integer"},"width":{"type":"integer","minimum":1,"maximum":120},"height":{"type":"integer","minimum":1,"maximum":120}},"required":[],"additionalProperties":false}}},{"type":"object","required":["request_id","action"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"wait"},"params":{"type":"object","properties":{},"required":[],"additionalProperties":false}}},{"type":"object","required":["request_id","action"],"properties":{"input_order":{"type":"object","required":["stream","sequence"],"additionalProperties":false,"description":"Optional ordered input stream. Send concurrent requests starting at sequence 0; retries reuse the same sequence and request_id. Gaps expire after five seconds.","properties":{"stream":{"type":"string","minLength":1,"maxLength":100},"sequence":{"type":"integer","minimum":0}}},"request_id":{"type":"string","minLength":1,"maxLength":100},"action":{"const":"undo"},"params":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}]}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActResponse"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActResponse"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActResponse"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/heartbeat":{"post":{"summary":"Renew presence without changing position","operationId":"post__players_id_heartbeat","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/leave":{"post":{"summary":"Leave this round","operationId":"post__players_id_leave","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/run":{"post":{"summary":"Start an Anthropic autopilot","operationId":"post__players_id_run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["goal","anthropic_api_key"],"properties":{"goal":{"type":"string"},"anthropic_api_key":{"type":"string","writeOnly":true},"model":{"type":"string"},"budget_usd":{"type":"number","minimum":0.01,"maximum":100,"default":1}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/stop":{"post":{"summary":"Stop the player’s autopilot and dash","operationId":"post__players_id_stop","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/transcript":{"get":{"summary":"Read run status and transcript entries after a sequence number","operationId":"get__players_id_transcript","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"run_id","in":"query","schema":{"type":"string"}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/players/{id}/notebook":{"get":{"summary":"Read persistent notes and scripts","operationId":"get__players_id_notebook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Replace notes and validated gameplay scripts","operationId":"put__players_id_notebook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"playerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes","scripts"],"properties":{"notes":{"type":"array","items":{"type":"string"},"maxItems":100},"scripts":{"type":"object"}}}}}},"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotebookResponse"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/legacy/high-scores":{"get":{"summary":"Read historical single-player records without accepting client results","operationId":"get__legacy_high_scores","parameters":[],"security":[],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results":{"get":{"summary":"Read server-derived multiplayer results","operationId":"get__results","parameters":[],"security":[],"responses":{"200":{"description":"Success; act responses include outcome and fresh observation.","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"World or player created; includes worldId, playerId and token.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Autopilot started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid command or fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Player token required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invite or ownership required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"World or player state conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Player movement is still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Storage or generation unavailable; do not assume a command committed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"meaning":{"type":"string"}},"required":["error","meaning"]},"Credentials":{"type":"object","properties":{"worldId":{"type":"string","format":"uuid"},"playerId":{"type":"string","format":"uuid"},"token":{"type":"string"}},"required":["worldId","playerId","token"]},"CreatedWorld":{"allOf":[{"$ref":"#/components/schemas/Credentials"},{"type":"object","properties":{"invite":{"type":"string","format":"uri"}},"required":["invite"]}]},"Coordinate":{"type":"object","properties":{"x":{"type":"integer"},"y":{"type":"integer"}},"required":["x","y"]},"Player":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"controller":{"enum":["human","external","autopilot"]},"position":{"$ref":"#/components/schemas/Coordinate"},"active":{"type":"boolean"},"color":{"type":"string"},"moves":{"type":"integer"},"pushes":{"type":"integer"}},"required":["id","name","controller","position","active","color","moves","pushes"]},"Observation":{"type":"object","properties":{"world_id":{"type":"string"},"player_id":{"type":"string"},"revision":{"type":"integer"},"status":{"enum":["preparing","playing","finished","error"]},"winner":{"type":["string","null"]},"position":{"$ref":"#/components/schemas/Coordinate"},"origin":{"$ref":"#/components/schemas/Coordinate"},"grid_orientation":{"const":"north-up"},"view":{"type":"array","items":{"type":"string"}},"elevation":{"type":"array","items":{"type":"string"}},"legend":{"type":"object","additionalProperties":{"type":"string"}},"inventory":{"type":"object","properties":{"cubes":{"type":"integer"},"abilities":{"type":"array","items":{"type":"string"}}},"required":["cubes","abilities"]},"players":{"type":"array","items":{"$ref":"#/components/schemas/Player"}},"objects":{"type":"object","description":"Visible crates, great_crates, goals, cubes, directional doors, shrines, minor_puzzles, instruction, dead_rooms, and dead_crates. No solution certificates."},"undo":{"$ref":"#/components/schemas/Undo"},"available_actions":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}},"required":["world_id","player_id","revision","status","winner","position","origin","grid_orientation","view","elevation","legend","inventory","players","objects","undo","available_actions"]},"Tool":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","description":"JSON Schema for tool arguments."}},"required":["name","description","input_schema"]},"Undo":{"type":"object","properties":{"cost":{"type":"integer","description":"Light cubes the next undo costs."},"refused":{"type":["string","null"],"enum":["nothing","far","cubes","moved","blocked","occupied",null],"description":"Why undo is refused right now; null when it can be taken."},"meaning":{"type":["string","null"]}},"required":["cost","refused","meaning"]},"Outcome":{"type":"object","properties":{"kind":{"type":"string"},"duration":{"type":"integer","description":"Movement duration in milliseconds."},"revision":{"type":"integer"},"reason":{"type":"string"}},"required":["kind","duration","revision"]},"ActResponse":{"type":"object","properties":{"outcome":{"$ref":"#/components/schemas/Outcome"},"observation":{"$ref":"#/components/schemas/Observation"}},"required":["outcome","observation"]},"ObserveResponse":{"type":"object","properties":{"observation":{"$ref":"#/components/schemas/Observation"}},"required":["observation"]},"GameView":{"type":"object","properties":{"acknowledgedInputs":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"round":{"type":"integer"},"revision":{"type":"integer"},"seed":{"type":"integer"},"difficulty":{"type":"string"},"owner":{"type":"boolean"},"invite":{"type":"string"},"self":{"type":"string"},"players":{"type":"array","items":{"$ref":"#/components/schemas/Player"}},"world":{"type":["object","null"],"description":"Loaded rendering terrain and public puzzle geometry; maps, sets, and typed arrays use the tagged codec documented in multiplayer-api.md."},"state":{"type":["object","null"],"description":"Public shared objects plus the observing player’s personal state, using the tagged codec."},"cubes":{"type":"integer"},"winner":{"type":["string","null"]},"status":{"enum":["preparing","playing","finished","error"]},"error":{"type":["string","null"]},"pending":{"type":"integer"},"dashing":{"type":"boolean"},"undo":{"$ref":"#/components/schemas/Undo"},"deadRooms":{"type":"object"},"deadCrates":{"type":"object"},"lastEvent":{"type":["object","null"]}},"required":["acknowledgedInputs","id","round","revision","seed","difficulty","owner","invite","self","players","world","state","cubes","winner","status","error","pending","dashing","undo","deadRooms","deadCrates","lastEvent"]},"WorldResponse":{"type":"object","properties":{"view":{"$ref":"#/components/schemas/GameView"}},"required":["view"]},"Notebook":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"string"}},"scripts":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"action":{"enum":["step","dash","hold","release","observe","wait","undo"]},"params":{"type":"object"}},"required":["action","params"]}}}},"required":["notes","scripts"]},"NotebookResponse":{"type":"object","properties":{"notebook":{"$ref":"#/components/schemas/Notebook"}},"required":["notebook"]},"Run":{"type":"object","properties":{"id":{"type":"string"},"goal":{"type":"string"},"model":{"type":"string"},"status":{"enum":["running","stopped","finished","error","interrupted"]},"budget":{"type":"number"},"spent":{"type":"number"},"turns":{"type":"integer"},"transcript":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer"},"type":{"enum":["status","message","tool_use","tool_result","error"]},"text":{"type":"string"}},"required":["seq","type","text"]}}},"required":["id","goal","model","status","budget","spent","turns","transcript"]},"TranscriptResponse":{"type":"object","properties":{"run":{"anyOf":[{"$ref":"#/components/schemas/Run"},{"type":"null"}]},"runs":{"type":"array","items":{"type":"object","description":"Run metadata without transcript entries."}}},"required":["run","runs"]}},"securitySchemes":{"playerToken":{"type":"http","scheme":"bearer"},"playerId":{"type":"apiKey","in":"header","name":"X-Player-Id"}}},"x-agent-tools":[{"name":"step","description":"Step one tile, pushing or climbing when the rules allow. Human control: arrows or WASD.","input_schema":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]}},"required":["direction"],"additionalProperties":false}},{"name":"dash","description":"Run until blocked, a crate slides, or a great crate is heaved. Requires dash; otherwise takes one ordinary step. Human control: Space plus a direction.","input_schema":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]}},"required":["direction"],"additionalProperties":false}},{"name":"hold","description":"Keep walking this way without sending another command: the server steps you on its own clock until you release, the way is refused, or the intent lapses. Repeat it to refresh the intent; repeating the same direction never double-steps. Human control: holding an arrow or WASD key.","input_schema":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","left","right"]},"mode":{"type":"string","enum":["step","dash"],"default":"step"}},"required":["direction"],"additionalProperties":false}},{"name":"release","description":"Stop holding a direction. A hold released before it has stepped yields exactly one step, so a fast tap is never swallowed.","input_schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"observe","description":"Inspect a north-up map. Without bounds, shows 25×25 around you. Provide x, y, width, height to inspect up to the human view’s loaded 120×120 window.","input_schema":{"type":"object","properties":{"x":{"type":"integer"},"y":{"type":"integer"},"width":{"type":"integer","minimum":1,"maximum":120},"height":{"type":"integer","minimum":1,"maximum":120}},"required":[],"additionalProperties":false}},{"name":"wait","description":"Read a fresh observation without moving.","input_schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"undo","description":"Take your last crate move back: the crate returns to where it was and you return to where you stood before pushing it, forgetting the walk since. Costs light cubes, one more each time. Refused when nothing of yours is left to take back, when another player has moved that crate since, or when a player or crate stands where you or it would return; observations say whether it is available. Human control: Z or the Undo button.","input_schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}],"x-gameplay":{"max_players":8,"presence_lease_seconds":60,"default_view_size":25,"coordinate_system":"x east, y south; north-up","budget_policy":"Stop before the next model request once the budget is spent; the final request may exceed it."}}