{ "openapi": "3.1.0", "info": { "title": "Pixel Underworld Agent API", "version": "2.0.0", "description": "Use a dedicated guest account and exchange its game session for a one-hour agent token. Keep both credentials private." }, "servers": [ { "url": "https://pixel-underworld.com" } ], "components": { "securitySchemes": { "gameSession": { "type": "http", "scheme": "bearer", "description": "The account game session from guest or Google sign-in." }, "agentToken": { "type": "http", "scheme": "bearer", "description": "One-hour agent credential issued by /api/auth/agent-token." } } }, "paths": { "/api/status": { "get": { "summary": "Service status and agent availability", "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/auth/guest": { "post": { "summary": "Create a dedicated guest account", "security": [], "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/characters": { "get": { "summary": "List heroes", "security": [ { "gameSession": [] } ], "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "summary": "Create a hero", "security": [ { "gameSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/auth/agent-token": { "post": { "summary": "Issue a one-hour agent token; issuing a new one revokes the previous token", "security": [ { "gameSession": [] } ], "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/auth/agent-token/revoke": { "post": { "summary": "Revoke the current agent token", "security": [ { "gameSession": [] } ], "responses": { "204": { "description": "Revoked; no body" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/mcp": { "post": { "summary": "Stateless MCP Streamable HTTP endpoint", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "MCP JSON-RPC request" } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/game_session": { "post": { "summary": "List your heroes; open, inspect status, or close one agent session. Opening requires an idle hero. Close when finished.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "op": { "type": "string", "const": "list_characters" } }, "required": [ "op" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "type": "string", "const": "open" }, "char_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "combat_defaults": { "type": "object", "properties": { "preset": { "default": "balanced", "type": "string", "enum": [ "cautious", "balanced", "aggressive" ] }, "stance": { "default": "auto", "type": "string", "enum": [ "auto", "melee", "ranged" ] }, "skills": { "default": [], "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "max_casts": { "default": 5, "type": "integer", "minimum": 0, "maximum": 20 }, "mp_reserve": { "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "potion_below": { "default": 0.35, "type": "number", "minimum": 0, "maximum": 1 }, "max_potions": { "default": 1, "type": "integer", "minimum": 0, "maximum": 5 }, "retreat_below": { "default": 0.2, "type": "number", "minimum": 0, "maximum": 1 }, "leash_tiles": { "default": 20, "type": "number", "minimum": 2, "maximum": 40 }, "max_additional_enemies": { "default": 1, "type": "integer", "minimum": 0, "maximum": 4 }, "incidental_damage": { "default": true, "type": "boolean" } }, "required": [ "preset", "stance", "skills", "max_casts", "mp_reserve", "potion_below", "max_potions", "retreat_below", "leash_tiles", "max_additional_enemies", "incidental_damage" ], "additionalProperties": false }, "guard_policy": { "type": "object", "properties": { "potion_below": { "default": 0, "type": "number", "minimum": 0, "maximum": 1 }, "max_potions": { "default": 0, "type": "integer", "minimum": 0, "maximum": 1 } }, "required": [ "potion_below", "max_potions" ], "additionalProperties": false } }, "required": [ "op", "char_id", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "type": "string", "const": "status" }, "session_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "op", "session_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "type": "string", "const": "close" }, "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "op", "session_id", "request_id" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/game_act": { "post": { "summary": "Execute one bounded game intent. Use observed targets with map and epoch. Returns current state; running means observe, not resubmit. Dialogue choices are child commands. Follow current quest markers; do not infer hidden content.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expected_control_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "move_to" }, "target": { "anyOf": [ { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "x": { "type": "number" }, "z": { "type": "number" } }, "required": [ "map", "epoch", "x", "z" ], "additionalProperties": false }, { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "map", "epoch", "id" ], "additionalProperties": false } ] }, "tolerance": { "default": 0.8, "type": "number", "minimum": 0.3, "maximum": 2 }, "avoid_combat": { "default": true, "type": "boolean" }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "target", "tolerance", "avoid_combat", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fight" }, "target": { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "map", "epoch", "id" ], "additionalProperties": false }, "policy": { "type": "object", "properties": { "preset": { "default": "balanced", "type": "string", "enum": [ "cautious", "balanced", "aggressive" ] }, "stance": { "default": "auto", "type": "string", "enum": [ "auto", "melee", "ranged" ] }, "skills": { "default": [], "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "max_casts": { "default": 5, "type": "integer", "minimum": 0, "maximum": 20 }, "mp_reserve": { "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "potion_below": { "default": 0.35, "type": "number", "minimum": 0, "maximum": 1 }, "max_potions": { "default": 1, "type": "integer", "minimum": 0, "maximum": 5 }, "retreat_below": { "default": 0.2, "type": "number", "minimum": 0, "maximum": 1 }, "leash_tiles": { "default": 20, "type": "number", "minimum": 2, "maximum": 40 }, "max_additional_enemies": { "default": 1, "type": "integer", "minimum": 0, "maximum": 4 }, "incidental_damage": { "default": true, "type": "boolean" } }, "required": [ "preset", "stance", "skills", "max_casts", "mp_reserve", "potion_below", "max_potions", "retreat_below", "leash_tiles", "max_additional_enemies", "incidental_damage" ], "additionalProperties": false }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "target", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "strike_object" }, "target": { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "map", "epoch", "id" ], "additionalProperties": false }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "target", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "interact" }, "target": { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "map", "epoch", "id" ], "additionalProperties": false }, "approach": { "default": true, "type": "boolean" }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "target", "approach", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "retreat" }, "destination": { "type": "object", "properties": { "map": { "type": "string", "minLength": 1, "maxLength": 128 }, "epoch": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "x": { "type": "number" }, "z": { "type": "number" } }, "required": [ "map", "epoch", "x", "z" ], "additionalProperties": false }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "explore" }, "max_distance": { "type": "number", "minimum": 1, "maximum": 40 }, "horizon_s": { "default": 15, "type": "number", "minimum": 1, "maximum": 30 } }, "required": [ "type", "max_distance", "horizon_s" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "advance_dialogue" }, "dialogue_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "dialogue_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choose" }, "dialogue_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "choice_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "dialogue_id", "choice_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "close_ui" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "equip" }, "slot": { "type": "string", "enum": [ "weapon", "armor", "acc1", "acc2" ] }, "item_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] } }, "required": [ "type", "slot", "item_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "use" }, "item_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "item_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "slot_skill" }, "slot": { "type": "integer", "minimum": 1, "maximum": 4 }, "skill_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "slot", "skill_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "track_quest" }, "quest_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "quest_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy", "sell" ] }, "item_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "quantity": { "default": 1, "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "type", "item_id", "quantity" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "learn_skill" }, "skill_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "skill_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "join_caste" }, "caste_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "caste_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fast_travel" }, "destination_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "destination_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "save" } }, "required": [ "type" ], "additionalProperties": false } ] }, "wait_ms": { "default": 8000, "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "session_id", "request_id", "expected_control_version", "action", "wait_ms" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/game_observe": { "post": { "summary": "Current compact state and recent outcomes. Long-poll after_event for running actions. Reads do not extend play leases.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "after_event": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "wait_ms": { "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "detail": { "default": "standard", "type": "string", "enum": [ "brief", "standard" ] } }, "required": [ "session_id", "wait_ms", "detail" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/game_inspect": { "post": { "summary": "Details for known entities, owned items/skills, active quests, open shops, explored maps, or exact paged dialogue. Use kind quest id active for active quest details.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "entity", "item", "skill", "quest", "map", "shop", "dialogue" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "session_id", "kind", "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/game_cancel": { "post": { "summary": "Cancel one particular active action. Committed effects remain. Return current state before choosing the next action.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "action_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expected_control_version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "session_id", "request_id", "action_id", "expected_control_version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful JSON response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } } } }