HTTP API routes

Machine-readable spec: server/openapi/openapi.yaml, browsable at /api/docs (Redoc) on a running server. Both the table below and the YAML are generated from the same annotated Ktor routes.

Method	Path	Description
GET	/api/admin/auctions	List all auction listings, any status
POST	/api/admin/auctions/{id}/force-cancel	Force-cancels a listing: returns the item to the seller and refunds the highest bidder, no tax
GET	/api/admin/blocks	All registered block definitions
GET	/api/admin/chunks/discovered	All chunk coordinates generated so far (in-memory ∪ persisted)
GET	/api/admin/claims	All land claims
DELETE	/api/admin/claims/{id}	Delete a land claim
GET	/api/admin/claims/{id}	A single land claim
PUT	/api/admin/claims/{id}/bounds	Update a claim's Y bounds
PUT	/api/admin/claims/{id}/trust	Grant or revoke a player's trust on a claim (online or offline)
GET	/api/admin/classes	RPG class definitions, keyed by class name
GET	/api/admin/configs	Names of all whitelisted editable YAML config files
GET	/api/admin/configs/{...}	Raw YAML content of a whitelisted config file
PUT	/api/admin/configs/{...}	Overwrite a whitelisted config file's raw YAML content
PUT	/api/admin/gametime	Set the in-game time of day
GET	/api/admin/groups	All permission groups, including the virtual admin group
POST	/api/admin/groups	Create a permission group
DELETE	/api/admin/groups/{name}	Delete a group and unassign it from every account and character that has it
PUT	/api/admin/groups/{name}	Replace a group's permission list
GET	/api/admin/instances	All instance zones
POST	/api/admin/instances	Create an instance zone covering already-generated chunks
DELETE	/api/admin/instances/{id}	Delete an instance zone
GET	/api/admin/instances/{id}	A single instance zone
PUT	/api/admin/instances/{id}	Rename an instance zone
GET	/api/admin/instances/{id}/blocks	Non-air blocks in an instance zone, streamed as newline-delimited JSON (application/x-ndjson, one InstanceBlockDto per line), capped at 300000
PUT	/api/admin/instances/{id}/bounds	Update an instance zone's Y bounds
PUT	/api/admin/instances/{id}/chunks	Update the set of chunks covered by an instance zone
PUT	/api/admin/instances/{id}/enabled	Enable/disable an instance zone
PUT	/api/admin/instances/{id}/layout	Update an instance zone's clip planes and shortcut bar layout
GET	/api/admin/items	Item definitions, keyed by item type id
GET	/api/admin/loggers	All known loggers (Logback's registry) with their explicit and effective level — useful to raise verbosity for live debugging
PUT	/api/admin/loggers/{...}	Set a logger's level (TRACE/DEBUG/INFO/WARN/ERROR/OFF), or null to inherit from its parent again
GET	/api/admin/npc-types	NPC type definitions (codex info), keyed by type id
POST	/api/admin/npc-types/reload	Reload NPC type definitions from resources/entities and despawn live instances so the spawner recreates them with the new model. Use after editing an entity bbmodel/yaml.
GET	/api/admin/npcs	Live NPC instances with full animal/combat state
POST	/api/admin/npcs/{id}/chat-test	Send a message to a live chat_npc's LLM dialogue outside of any real player session — for iterating on its dialoguePrompt
POST	/api/admin/perf/reset	Start a perf measurement window: clears the world's tick samples and the process-level run metrics
GET	/api/admin/perf/snapshot	Tick percentiles per phase, heap/GC/CPU/network since the last perf reset
GET	/api/admin/permissions	Every known permission string — slash commands' permission field (discovered live from the command registry) plus the fixed set checked outside the command system. For autocomplete, not validation — a group may still be given any free-form permission string.
GET	/api/admin/plain-colors	All registered plain paint colors
GET	/api/admin/players	All player names
POST	/api/admin/players	Create a player identity in the target world and return its id. Reserves the id (and, with characterClass, a fresh RPG character) that onConnect will use — so an E2E test's RPG player is ready before the browser connects, with no character-creation screen. Also ensures the matching no-auth account exists. Does not write to persistence.
GET	/api/admin/players/{name}	Full player file (state, keybindings, RPG data)
PUT	/api/admin/players/{name}/equipment	Partially update a player's owned/equipped armor and wielded hand items
POST	/api/admin/players/{name}/give	Give an inventory item, or grant ownership of an armor/weapon/tool
GET	/api/admin/players/{name}/groups	A character's in-game RBAC groups — distinct from the account-level groups on /api/admin/users, which only gate this admin panel
PUT	/api/admin/players/{name}/groups	Replace a character's in-game RBAC groups
PUT	/api/admin/players/{name}/keybindings	Overwrite a player's saved key bindings
PUT	/api/admin/players/{name}/preferences	Partially update a player's preferences (only given fields change)
POST	/api/admin/players/{name}/rename	Rename a player
PUT	/api/admin/players/{name}/rpg	Partially update a player's RPG class/base stats
GET	/api/admin/protections	Each Class's Protection Spell and per-Rank values, keyed by class name (null spellId when a Class has none configured)
GET	/api/admin/protections/simulate	Per-Class survival report at a Level and Danger tier: active Protection Rank, hit chance and mean damage/attacks-survived with and without it, against that tier's real NPC Abilities. Analytic, no Monte-Carlo.
POST	/api/admin/reload	Reload configuration files without restarting the server — same behavior as the in-game /reload command
POST	/api/admin/restart	Trigger a pitchfork server restart
GET	/api/admin/scenes	All scenes (bounded off-world block-structure buffers)
POST	/api/admin/scenes	Create a scene
DELETE	/api/admin/scenes/{id}	Delete a scene
GET	/api/admin/scenes/{id}	A single scene's metadata
PUT	/api/admin/scenes/{id}	Rename a scene
GET	/api/admin/scenes/{id}/blocks/raw	Scene block/state/extraState buffers as a binary blob: 3×4-byte big-endian dimensions (width,height,depth) followed by the blocks byte array, then the states byte array, then the extraStates byte array (wire-index-per-byte, 0 = AIR)
PUT	/api/admin/scenes/{id}/dimensions	Resize a scene
POST	/api/admin/scenes/{id}/duplicate	Duplicate a scene (copies name, dimensions, and blocks)
GET	/api/admin/scenes/{id}/entities	Fractional (lego/plate/arch) block entities placed in this scene — not carried by the blocks/raw binary blob, so the client loads them separately on scene open
PUT	/api/admin/scenes/{id}/layout	Update a scene's shortcut bar layout
GET	/api/admin/schemas/{filename}	A JSON Schema file (data/config/schemas/*.schema.json) for the config editor
GET	/api/admin/simulation/defaults	Defaults the world simulator admin UI prefills its editors with
GET	/api/admin/skills	All attack and spell ids
GET	/api/admin/social/factions	Faction settings and definitions
POST	/api/admin/social/factions	Create or replace a faction definition (matched by id)
PUT	/api/admin/social/factions/settings	Update global faction settings
DELETE	/api/admin/social/factions/{id}	Delete a faction definition
GET	/api/admin/social/factions/{id}/members	Players affiliated with a faction (online + persisted)
POST	/api/admin/social/factions/{id}/members	Make a player join a faction (admin — no cooldown)
DELETE	/api/admin/social/factions/{id}/members/{playerId}	Remove a player from a faction
GET	/api/admin/social/groups	All active player groups
POST	/api/admin/social/groups	Create a group led by an online player
DELETE	/api/admin/social/groups/{id}	Disband a group
POST	/api/admin/social/groups/{id}/members	Add an online player to a group
DELETE	/api/admin/social/groups/{id}/members/{playerId}	Remove a member from a group
GET	/api/admin/social/guilds	All guilds
POST	/api/admin/social/guilds	Create a guild
DELETE	/api/admin/social/guilds/{id}	Disband a guild
PUT	/api/admin/social/guilds/{id}	Rename / retag / set MOTD of a guild
POST	/api/admin/social/guilds/{id}/members	Add a player to a guild
DELETE	/api/admin/social/guilds/{id}/members/{playerId}	Remove a member from a guild
PUT	/api/admin/social/guilds/{id}/members/{playerId}	Set a guild member's rank
GET	/api/admin/social/online-players	Names of currently connected players (group-member autocomplete)
GET	/api/admin/social/players	Canonical display names of every known player (online + persisted), de-duplicated — for social name-field autocomplete
GET	/api/admin/status	Server status snapshot (TPS, players, chunks, heap, CPU)
GET	/api/admin/users	All local/no-auth accounts
POST	/api/admin/users	Create a local/no-auth user account
DELETE	/api/admin/users/{email}	Delete a user account
PUT	/api/admin/users/{email}	Update a local user's display name/groups
GET	/api/admin/worlds	All worlds on disk, with stats
POST	/api/admin/worlds	Create a new world
GET	/api/admin/ws/instances/{id}
GET	/api/admin/ws/npcs
GET	/api/admin/ws/scenes/{id}
GET	/api/admin/ws/simulation
GET	/api/armors	List all armor definitions
GET	/api/assets/manifest
POST	/api/assets/reload
GET	/api/attacks	Attack definitions, flattened by "attackId:rank" key
GET	/api/auth/config	Active auth provider, used by the client to pick the right login UI
GET	/api/autocomplete/{commandId}/{argIndex}	Autocomplete suggestions for a slash command argument
GET	/api/biomes	Grass color per biome id, as [r, g, b] in 0..1
GET	/api/biomes/tints	Screen tint color per liquid biome id, as [r, g, b] in 0..1
POST	/api/character/create	Create a new (non-RPG) character
POST	/api/character/rpgcreate	Create a new RPG character (point-buy base stats + class)
GET	/api/chunks/{cx}/{cz}	Binary-encoded chunk data (protocol.ServerMessage.ChunkData wire format). Not a JSON API — used by the game client, not by TanStack Query hooks.
GET	/api/classes	Attacks and spells accessible per RPG class, keyed by level
GET	/api/furnitures	List all furniture definitions
GET	/api/game-assets	3D game asset files discovered under resources/game-assets
GET	/api/game-assets/bbmodel-export/{...}	Converts an OBJ/MTL mesh into a Blockbench-compatible mesh .bbmodel (cached). The generated mesh elements are not rendered by the admin viewer — open the result in Blockbench to edit it.
DELETE	/api/game-assets/blend-cache/{...}	Clears the cached Blender conversion (scene tree + all OBJ/bbmodel exports) for a .blend file
GET	/api/game-assets/blend-preview/{...}	Converts a .blend file to OBJ/MTL via headless Blender (cached) and returns the OBJ asset path
GET	/api/game-assets/blend-scene/{...}	Reads a .blend file's collection/object tree via headless Blender (cached)
GET	/api/game-assets/file/{...}	Raw asset file bytes (glb/gltf/fbx/textures)
GET	/api/i18n/{locale}	Client-facing translation keys for a locale
GET	/api/items/meta	Item metadata (label, background color, consumable flags) by item type id
GET	/api/keybindings	Key bindings — a player's saved bindings if ?player= is given and persistence is available, otherwise the default config
GET	/api/layout/registry	All widgets registered for the UI layout editor
GET	/api/macros/context	Variables available to the macro JEXL evaluation context
GET	/api/map/houses	Generated houses within an area
GET	/api/map/road-raster	Per-chunk road bitmask within an area
GET	/api/map/road-raster.png	Rasterized road overlay as a PNG image
GET	/api/map/roads	Road vertex segments within an area
GET	/api/map/staircases	Named staircase points for the map overlay
GET	/api/map/state	Live players, NPCs and weather zones for the map overlay
GET	/api/map/terrain	Cached terrain summary JSON for the map overlay
GET	/api/map/terrain-raster.png	Rasterized terrain overlay as a PNG image
GET	/api/map/voronoi	Voronoi biome cells around a point
GET	/api/map/voronoi-borders	Voronoi cell border segments within an area
GET	/api/minigames	List all registered mini-games (id, display name, bundle URL)
GET	/api/player/{id}/armors	Armor names currently equipped by a player
GET	/api/player/{id}/hands	Wielded weapon/tool names and dominant hand for a player
GET	/api/player/{id}/owned	Armor/weapon/tool names owned by a player
GET	/api/player/{id}/rpg	A player's RPG character class
POST	/api/player/{id}/screenshots	Upload a player screenshot (base64 PNG, optionally as a data: URI)
GET	/api/player/{id}/skin	A player's current skin
PUT	/api/player/{id}/skin	Change a player's skin
GET	/api/players/by-email/{email}	Player characters (name + id) linked to an account email
GET	/api/players/names	Names of all known players
GET	/api/quests	All quest definitions
GET	/api/server/info	Server build timestamp and protocol fingerprint
GET	/api/siege-weapons	List all siege weapon definitions
GET	/api/skins	Names of all available player skins
GET	/api/skins/{name}/config	Skin config (eye offset, hidden bones) for a named skin
GET	/api/spells	Spell definitions, flattened by "spellId:rank" key
GET	/api/tools	List all tool definitions
GET	/api/vehicles/{name}/config	Vehicle model config (speed, seat offset) for a named vehicle
GET	/api/weapons	List all weapon definitions
GET	/auth/callback	OAuth authorization code callback — redirects with the session token in the URL fragment
POST	/auth/login	Log in with email/password (local auth provider)
GET	/auth/me	Resolve the current session from its bearer token
GET	/auth/oauth/start	Redirect to the OAuth provider's consent screen
POST	/auth/refresh	Exchange a refresh token for a new access token + rotated refresh token