{"info":{"description":"Public REST API for Minebox.","title":"Minebox API","version":"1.2.0"},"openapi":"3.0.3","paths":{"/attributes":{"get":{"description":"Returns every player stat/attribute (strength, wisdom, the fortune types, stamina, …) with its localised name, display colour, value sign and description.","operationId":"get_attributes","parameters":[{"description":"Locale for the attribute name","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"attributes":[{"color":"#886EF6","description":"Boosts experience and skill gains.","id":"wisdom","name":"Wisdom","sign":"+"},{"color":"#A0826D","description":"Extra ores dropped while mining.","id":"mining_fortune","name":"Mining Fortune","sign":"+"}],"total":22}}},"description":"Attribute list"}},"summary":"List all attributes (player stats)","tags":["Game Data"]}},"/bestiary":{"get":{"description":"Returns a paginated, filterable, sortable list of creatures in the bestiary with translated names.","operationId":"get_bestiary","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Page number","in":"query","name":"page","required":false,"schema":{"default":"1","type":"integer"}},{"description":"Creatures per page (max 50)","in":"query","name":"pageSize","required":false,"schema":{"default":"50","type":"integer"}},{"description":"Sort key","in":"query","name":"sort","required":false,"schema":{"default":"level","enum":["level","nameAsc","nameDesc","family"],"type":"string"}},{"description":"Search by creature name or ID (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"Filter by family","in":"query","name":"family","required":false,"schema":{"type":"string"}},{"description":"Filter by zone","in":"query","name":"zone","required":false,"schema":{"type":"string"}},{"description":"If true, only return bosses","in":"query","name":"boss","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"creatures":[{"family":"undead","family_name":"Undead","health":250,"id":"zombie_warrior","image":"https://cdn2.minebox.co/data/mobs/zombie_warrior.gif","level":15,"name":"Zombie Warrior"}],"families":[{"id":"undead","name":"Undead"}],"page":1,"pageSize":50,"total":120}}},"description":"Paginated creature list"}},"summary":"List all creatures","tags":["Bestiary"]}},"/bestiary/{id}":{"get":{"description":"Returns full creature details including drops, stats, and zone information.","operationId":"get_bestiary_id","parameters":[{"description":"Creature ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"drops":[{"chance":0.15,"item_id":"rotten_blade"}],"family":"undead","family_name":"Undead","health":250,"id":"zombie_warrior","image":"https://cdn2.minebox.co/data/mobs/zombie_warrior.gif","level":15,"name":"Zombie Warrior","stats":{"attack":30,"defense":10},"zone":"dark_forest"}}},"description":"Creature details"},"404":{"description":"Creature not found"}},"summary":"Get a creature's details","tags":["Bestiary"]}},"/classes":{"get":{"description":"Returns all character classes with translated names, descriptions, and stats. Spells granted by a class are exposed under `spell_unlocks` as a map of class level → list of spell IDs unlocked at that level (level 1 = starting spells).","operationId":"get_classes","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"classes":[{"description":"A sturdy melee fighter.","id":"warrior","name":"Warrior","spell_unlocks":{"1":["slash"],"3":["shield_bash"]},"types":["DAMAGE"]}],"total":5}}},"description":"Class list"}},"summary":"List all classes","tags":["Game Data"]}},"/classes/{id}":{"get":{"description":"Returns full class details with translated name, description, and lore. See `/classes` for the `spell_unlocks` shape.","operationId":"get_classes_id","parameters":[{"description":"Class ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"description":"Class details"},"404":{"description":"Class not found"}},"summary":"Get a class's details","tags":["Game Data"]}},"/collections":{"get":{"description":"Returns resource collections for the given category with progression tiers and translated names. The `category` query parameter is required.","operationId":"get_collections","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Category (mining, fishing, farming, etc.)","in":"query","name":"category","required":true,"schema":{"type":"string"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"collections":[{"category":"mining","id":"amethyst_shard","item":"material-amethyst_shard","levels":[{"amount":1},{"amount":12},{"amount":25}],"name":"Amethyst Shard"}],"total":60}}},"description":"Collection list"}},"summary":"List collections for a category","tags":["Game Data"]}},"/cosmetics":{"get":{"description":"Returns cosmetic items (titles, emotes, nameplates, balloons, profile plates, tags) with icons. Supports locale translation, category filtering, and search.","operationId":"get_cosmetics","parameters":[{"description":"Locale code for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Filter by category (title, emote, nameplate, balloon, profile_plate, tag)","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Search by name or ID","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"cosmetics":[{"category":"balloon","icon":"data:image/png;base64,...","id":"ice_cream","lore":"Floats like a dream.","name":"Ice Cream Balloon","rarity":"RARE"}],"total":109}}},"description":"List of cosmetics"}},"summary":"List all cosmetics","tags":["Game Data"]}},"/data/{identifier}":{"get":{"description":"Returns detailed player data: level, playtime, stats, skills, companions, objectives, and more. Accepts a username or UUID. Respects the player's privacy flag. Skill experience is exposed under `SKILLS.data` as the per-skill in-game total (base earned XP plus the bonus granted dynamically by the player's achievements/collections). Skill keys are uppercase (e.g. `MINER`).","operationId":"get_data_identifier","parameters":[{"description":"Minecraft username or UUID","in":"path","name":"identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"SKILLS":{"data":{"MINER":2000}}},"id":"069a79f4-44e9-4726-a5be-fca90e38aaf5","level":42,"online":false,"playtime":123456,"username":"Notch"}}},"description":"Player profile"},"401":{"content":{"application/json":{"example":{"error":"User does not allow API requests"}}},"description":"Player has disabled API access"},"404":{"content":{"application/json":{"example":{"error":"User not found"}}},"description":"User not found"}},"summary":"Get a player's full profile","tags":["Players"]}},"/effects":{"get":{"description":"Returns all stat effects with translated names and icons. `duration` is how long the effect lasts (seconds) when applied; it comes from the item that grants the effect, so effects with no granting item (beacon auras, mob debuffs) omit it. When an effect is granted by several items with differing durations (candies and their enchanted variants, etc.), `duration` is the base/shortest value and `durations` breaks it down per granting item.","operationId":"get_effects","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"effects":[{"duration":28800,"icon":"data:image/png;base64,...","id":"mixed_fruit_salad","name":"Mixed fruit salad"},{"duration":3600,"durations":[{"duration":3600,"item":"candy_fortune"},{"duration":43200,"item":"candy_enchanted_fortune"}],"icon":"data:image/png;base64,...","id":"candy_fortune","name":"Fortune Candy"}],"total":115}}},"description":"Effect list"}},"summary":"List all effects","tags":["Game Data"]}},"/guild/{identifier}":{"get":{"description":"Returns guild information including members, level, XP, and banner. Accepts a guild name (case-insensitive) or UUID.","operationId":"get_guild_identifier","parameters":[{"description":"Guild name or UUID","in":"path","name":"identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"banner":"yell bor mc","id":"a1b2c3d4","level":5,"members":[{"is_owner":true,"online":true,"username":"Notch"},{"is_owner":false,"online":false,"username":"jeb_"}],"name":"SwordLords","xp":12000}}},"description":"Guild details"},"404":{"description":"Guild not found"}},"summary":"Get guild details","tags":["Guilds"]}},"/guilds":{"get":{"description":"Returns named guilds with their id, banner, level, XP and member count, ordered by level then XP descending. Paginated with `limit` (default 50, max 100) and `offset` (default 0); `total` is the full count of named guilds so clients can page through.","operationId":"get_guilds","parameters":[{"description":"Page size (default 50, max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}},{"description":"Number of guilds to skip (default 0)","in":"query","name":"offset","required":false,"schema":{"default":"0","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"guilds":[{"banner":"yell bor mc","id":"a1b2c3d4","level":5,"members":15,"name":"SwordLords","xp":12000}],"limit":50,"offset":0,"total":120}}},"description":"Paginated guild list"}},"summary":"List all guilds","tags":["Guilds"]}},"/harvestables":{"get":{"description":"Returns all harvestable resources across categories (fish, ores, trees, plants, crops) with their drops, minimum level, and translated names. Fish drops are flattened from the underlying conditional chance table to a single base chance per item.","operationId":"get_harvestables","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"harvestables":[{"category":"ores","drops":[{"amount":"2-4","chance":1,"item":"material-coal"}],"id":"coal","min_level":"1","name":"Coal Ore"},{"category":"fish","drops":[{"amount":"1","chance":45,"item":"mbi-fish_mandarinfish"},{"amount":"1","chance":60,"item":"mbi-fish_breaded_fish"}],"id":"shoal_tropical","min_level":"1","name":"Tropical Shoal"}],"total":80}}},"description":"Harvestable list"}},"summary":"List all harvestable resources","tags":["Game Data"]}},"/item/{id}":{"get":{"description":"Returns full item details including recipe, effects, and the list of recipes this item is used in.","operationId":"get_item_id","parameters":[{"description":"Item ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"category":"weapon","extra_image":"(only for pet/mount items) https://cdn2.minebox.co/data/mobs/{model}.gif","id":"iron_sword","level":5,"lore":"A sturdy blade.","name":"Iron Sword","rarity":"common","stats":{"damage":[10,15]}}}},"description":"Item details"},"404":{"description":"Item not found"}},"summary":"Get a single item","tags":["Items"]}},"/items":{"get":{"description":"Returns a paginated, filterable, sortable list of game items with translated names.","operationId":"get_items","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Page number","in":"query","name":"page","required":false,"schema":{"default":"1","type":"integer"}},{"description":"Items per page (max 50)","in":"query","name":"pageSize","required":false,"schema":{"default":"50","type":"integer"}},{"description":"Sort key","in":"query","name":"sort","required":false,"schema":{"default":"level","enum":["level","rarity","nameAsc","nameDesc"],"type":"string"}},{"description":"Filter by item type (repeatable, e.g. MUSIC_DISC, RING, PET). Aliases: 'type' and 'category' (single value).","in":"query","name":"categories","required":false,"schema":{"type":"string"}},{"description":"Alias of categories (single value)","in":"query","name":"type","required":false,"schema":{"type":"string"}},{"description":"Alias of categories (single value)","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Filter by rarity","in":"query","name":"rarity","required":false,"schema":{"type":"string"}},{"description":"Filter by crafting job","in":"query","name":"job","required":false,"schema":{"type":"string"}},{"description":"Minimum level","in":"query","name":"levelMin","required":false,"schema":{"default":"0","type":"integer"}},{"description":"Maximum level","in":"query","name":"levelMax","required":false,"schema":{"default":"100","type":"integer"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"JSON array of stat filters [{stat, min, max}]","in":"query","name":"stats","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"category":"weapon","id":"iron_sword","level":5,"name":"Iron Sword","rarity":"common"},{"category":"pet","extra_image":"https://cdn2.minebox.co/data/mobs/pet_birb_blue.gif","id":"pet_birb_blue","level":10,"name":"Blue Birb","rarity":"rare"},{"category":"mount","extra_image":"https://cdn2.minebox.co/data/mobs/mount_cloud.gif","id":"mount_cloud","level":1,"name":"Cloud","rarity":"mythic"}],"page":1,"pageSize":50,"total":350}}},"description":"Paginated item list"}},"summary":"List all game items","tags":["Items"]}},"/leaderboard/currency":{"get":{"description":"Returns the top players ranked by a currency type. Gold includes bank gold.","operationId":"get_leaderboard_currency","parameters":[{"description":"Currency type","in":"query","name":"type","required":true,"schema":{"enum":["gold","trophies","votes","crystals"],"type":"string"}},{"description":"Number of entries (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"leaderboard":[{"username":"Notch","value":1500000}],"total":50,"type":"gold"}}},"description":"Currency leaderboard"},"400":{"description":"Invalid currency type"}},"summary":"Currency leaderboard","tags":["Leaderboards"]}},"/leaderboard/guilds":{"get":{"description":"Returns the top guilds ranked by level and XP.","operationId":"get_leaderboard_guilds","parameters":[{"description":"Number of guilds to return (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"guilds":[{"level":10,"members":15,"name":"SwordLords"}],"total":50}}},"description":"Guild leaderboard"}},"summary":"Guild leaderboard","tags":["Leaderboards"]}},"/leaderboard/players":{"get":{"description":"Returns the server leaderboard for the given type (levels, etc.).","operationId":"get_leaderboard_players","parameters":[{"description":"Leaderboard type","in":"query","name":"type","required":false,"schema":{"default":"levels","type":"string"}},{"description":"Season number (optional)","in":"query","name":"season","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"leaderboard":[{"username":"Notch","value":42}],"update_in":60}}},"description":"Leaderboard entries"}},"summary":"Player leaderboard","tags":["Leaderboards"]}},"/leaderboard/pvp":{"get":{"description":"Returns the top PvP players ranked by ELO.","operationId":"get_leaderboard_pvp","parameters":[{"description":"Number of entries (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"leaderboard":[{"elo":1800,"losses":30,"rank_tier":"MASTER","trophies":5,"username":"Notch","wins":200}],"total":50}}},"description":"PvP leaderboard"}},"summary":"Player PvP leaderboard","tags":["Leaderboards"]}},"/leaderboard/pvp-guilds":{"get":{"description":"Returns the top guilds ranked by PvP ELO.","operationId":"get_leaderboard_pvp_guilds","parameters":[{"description":"Number of entries (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"leaderboard":[{"elo":1800,"guild_name":"SwordLords","losses":15,"rank_tier":"MASTER","wins":100}],"total":50}}},"description":"Guild PvP leaderboard"}},"summary":"Guild PvP leaderboard","tags":["Leaderboards"]}},"/market/auction":{"get":{"description":"Returns current auction house listings with pagination, sorting, and optional filtering by item or rarity. Each listing includes the item `level`, the exact rolled `stats` parsed from the item instance, and (for weapons) `damages` as [min, max] ranges from the item catalog. `total` is the full number of listings matching the current filters (independent of `limit`/`offset`), so clients can page to the end.","operationId":"get_market_auction","parameters":[{"description":"Filter by exact item ID (takes precedence over rarity)","in":"query","name":"item_id","required":false,"schema":{"type":"string"}},{"description":"Number of listings to return (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}},{"description":"Offset for pagination","in":"query","name":"offset","required":false,"schema":{"default":"0","type":"integer"}},{"description":"Sort field","in":"query","name":"sort","required":false,"schema":{"default":"time","enum":["time","price","level"],"type":"string"}},{"description":"Sort direction","in":"query","name":"sort_direction","required":false,"schema":{"default":"desc","enum":["asc","desc"],"type":"string"}},{"description":"Filter by rarity (ignored when item_id is set)","in":"query","name":"rarity","required":false,"schema":{"enum":["common","uncommon","rare","epic","legendary","mythic"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"listings":[{"author":"Notch","created_at":"2025-01-08T12:00:00Z","damages":{"AIR":[3,4]},"expires_at":"2025-01-15T12:00:00Z","id":1234,"item_id":"mbi-staff_balloon_boomstick","level":4,"order_type":"SELL","price_per_unit":5000,"quantity":1,"stats":{"AGILITY":5}}],"total":25}}},"description":"Active auction listings"}},"summary":"List active auction listings","tags":["Market"]}},"/market/bazaar":{"get":{"description":"Returns bazaar items with their current buy/sell prices and available stock. Each item carries its `category` (top-level, e.g. `farming`) and `subcategory` (e.g. `wheat`). Results are in a stable item-id order, so paging with `offset`/`limit` is a consistent, non-overlapping walk of the full set; `total` is the full item count. By default the list also includes every sellable item that currently has no offer, as a 0/0/0 entry (set `include_empty=false` for active-only). The complete sellable set + category tree is also available on `/market/catalog`.","operationId":"get_market_bazaar","parameters":[{"description":"Filter by item ID","in":"query","name":"item_id","required":false,"schema":{"type":"string"}},{"description":"Number of items to return (max 100)","in":"query","name":"limit","required":false,"schema":{"default":"50","type":"integer"}},{"description":"Offset for pagination","in":"query","name":"offset","required":false,"schema":{"default":"0","type":"integer"}},{"description":"Include sellable items with no active offer (0/0/0)","in":"query","name":"include_empty","required":false,"schema":{"default":"true","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"buy_price":50,"category":"farming","item_id":"material-wheat","sell_price":10,"stock":5000,"subcategory":"wheat"}],"total":917}}},"description":"Bazaar item list"}},"summary":"List bazaar items","tags":["Market"]}},"/market/catalog":{"get":{"description":"Returns the static catalog of what is sellable in the bazaar: the category/subcategory tree and a flat list of every sellable item with its `category`, `subcategory` and `market_type`. This is catalog data only (no prices) — use `/market/bazaar` for live prices/stock. Sourced from the game config and served via the CDN.","operationId":"get_market_catalog","responses":{"200":{"content":{"application/json":{"example":{"bazaar":{"categories":[{"id":"farming","subcategories":[{"id":"wheat","items":["material-wheat","mbi-enchanted_material-wheat"],"market_type":"bazaar-wheat"}]}],"items":[{"category":"farming","id":"material-wheat","market_type":"bazaar-wheat","subcategory":"wheat"}]}}}},"description":"Sellable-item catalog"}},"summary":"Bazaar/auction sellable catalog","tags":["Market"]}},"/market/fees":{"get":{"description":"Returns the sale tax and the price-tiered listing fee schedule so clients can compute exact profits. Sale tax = price * sale_tax_percent/100 (deducted from payout). Listing fee = price * tier.percent/100, where tier is the first listing_fee_tiers entry with price \u003c= max_price. SubPlus subscribers pay sub_plus_multiplier (0.5 = -50%) on both.","operationId":"get_market_fees","responses":{"200":{"content":{"application/json":{"example":{"gem_exchange_tax_percent":10,"listing_fee_tiers":[{"max_price":1000000,"percent":1},{"max_price":10000000,"percent":2},{"max_price":100000000,"percent":3},{"max_price":1000000000,"percent":4},{"max_price":999999999999,"percent":5}],"sale_tax_percent":1,"sub_plus_multiplier":0.5}}},"description":"Market fee schedule"}},"summary":"Auction house tax \u0026 listing fees","tags":["Market"]}},"/market/gem-exchange":{"get":{"description":"Returns current gem exchange buy and sell orders.","operationId":"get_market_gem_exchange","parameters":[{"description":"Filter by order type","in":"query","name":"type","required":false,"schema":{"enum":["buy","sell"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"orders":[{"created_at":"2025-01-15T12:00:00Z","expires_at":"2025-01-22T12:00:00Z","id":1,"order_type":"SELL","price_per_unit":500,"quantity":100,"username":"Notch"}],"total":10}}},"description":"Gem exchange orders"}},"summary":"List gem exchange orders","tags":["Market"]}},"/market/prices":{"get":{"description":"Returns average price data over time for a specific item, broken down by transaction type (DIRECT, BUY, SELL).","operationId":"get_market_prices","parameters":[{"description":"Item ID to get stats for","in":"query","name":"item_id","required":true,"schema":{"type":"string"}},{"description":"Time period","in":"query","name":"period","required":false,"schema":{"enum":["day","week","month","year"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"BUY":null,"DIRECT":{"values":[[1700000000,150.5]]},"SELL":null}}},"description":"Price statistics by transaction type"}},"summary":"Get price statistics","tags":["Market"]}},"/me":{"get":{"description":"Returns the profile of the player owning the `Authorization: Bearer \u003caccess_token\u003e`. Requires the `profile` scope.","operationId":"get_me","responses":{"200":{"content":{"application/json":{"example":{"discord_id":"123…","guild":{"id":"…","name":"Qore"},"id":"…","level":42,"online":true,"username":"Notch"}}},"description":"Player profile"},"401":{"content":{"application/json":{"example":{"error":"invalid_token","error_description":"Invalid or expired access token."}}},"description":"Missing/invalid access token"}},"summary":"Authenticated player profile","tags":["Account"]}},"/museum":{"get":{"description":"Returns the item ids donatable to the museum, grouped by category (e.g. `tool`, `sword`, `ore`, `art`). Pass `category` to fetch a single category's items. Resolve item details (name, rarity, image) via `/items`.","operationId":"get_museum","parameters":[{"description":"Museum category (e.g. tool, sword, ore, art)","in":"query","name":"category","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"sword":["adventurer_sword","banana_sword"],"tool":["hammer_ruby","pickaxe_iron"]}}},"description":"Donatable item ids grouped by category"},"404":{"description":"Unknown category (when ?category= is set)"}},"summary":"List museum-donatable items by category","tags":["Game Data"]}},"/oauth/discord/login":{"get":{"description":"Begins the Discord-federated login: redirects the browser to Discord (`identify` scope). On success the user is redirected to the configured website URL with `access_token`, `refresh_token`, `token_type`, `expires_in` in the URL fragment (or returns them as JSON if no redirect is configured). The Discord account must be linked to a Minebox account (in-game `/discord link`).","operationId":"get_oauth_discord_login","responses":{"302":{"description":"Redirect to Discord"},"403":{"content":{"application/json":{"example":{"error":"not_linked","error_description":"This Discord account isn't linked to a Minebox account…"}}},"description":"Discord account not linked / API access disabled"}},"summary":"Start Discord login","tags":["Account"]}},"/oauth/refresh":{"post":{"description":"Exchanges a (single-use, rotating) `refresh_token` for a fresh access token + refresh token.","operationId":"post_oauth_refresh","parameters":[{"description":"The refresh token (form-encoded body)","in":"query","name":"refresh_token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"access_token":"…","expires_in":3600,"refresh_token":"…","token_type":"Bearer"}}},"description":"New tokens"},"401":{"description":"Invalid/expired refresh token"}},"summary":"Refresh access token","tags":["Account"]}},"/ping":{"get":{"description":"","operationId":"get_ping","responses":{"200":{"content":{"application/json":{"example":{"message":"pong"}}},"description":"Service is running"}},"summary":"Health check","tags":["System"]}},"/pvp/guild/stats/{identifier}":{"get":{"description":"Returns PvP statistics for a guild including ELO, wins/losses, win streak, and rank tier. Accepts a guild name (case-insensitive) or UUID.","operationId":"get_pvp_guild_stats_identifier","parameters":[{"description":"Guild name or UUID","in":"path","name":"identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"elo":1650,"guild_id":"a1b2c3d4-...","guild_name":"SwordLords","losses":20,"rank_tier":"GOLD","win_streak":5,"wins":80}}},"description":"Guild PvP statistics"},"404":{"description":"Guild not found or has no PvP stats"}},"summary":"Get a guild's PvP stats","tags":["Guilds"]}},"/pvp/stats/{username}":{"get":{"description":"Returns PvP statistics for a player including ELO, wins/losses, trophies, kill/death ratio, and rank tier.","operationId":"get_pvp_stats_username","parameters":[{"description":"Minecraft username","in":"path","name":"username","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"best_win_streak":15,"draws":5,"elo":1450,"losses":45,"rank_tier":"GOLD","total_deaths":180,"total_kills":350,"trophies":3,"user_id":"069a79f4","username":"Notch","win_streak":7,"wins":120}}},"description":"PvP statistics"},"404":{"description":"Player not found or has no PvP stats"}},"summary":"Get a player's PvP stats","tags":["Players"]}},"/rarities":{"get":{"description":"Returns all rarity tiers with order, translated name, and icon.","operationId":"get_rarities","parameters":[{"description":"Locale code for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"rarities":[{"icon":"data:image/png;base64,...","id":"common","name":"Common","order":1},{"icon":"data:image/png;base64,...","id":"legendary","name":"Legendary","order":5}],"total":7}}},"description":"List of rarities"}},"summary":"List all rarities","tags":["Game Data"]}},"/recipes":{"get":{"description":"Returns crafting recipes for the given job with translated output names. The `job` query parameter is required. Each recipe includes `experience {start, end, max_level}` = the craft XP, which scales linearly from `start` (at the recipe's min level) down to `end` (at `max_level`).","operationId":"get_recipes","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Crafting job (MINER, BLACKSMITH, etc.)","in":"query","name":"job","required":true,"schema":{"type":"string"}},{"description":"Search by recipe name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"recipes":[{"amount":1,"experience":{"end":400,"max_level":90,"start":800},"id":"iron_sword_recipe","ingredients":[{"amount":3,"id":"iron_ingot","type":"vanilla"}],"job":"BLACKSMITH","name":"Iron Sword","output":"iron_sword"}],"total":150}}},"description":"Recipe list"}},"summary":"List crafting recipes for a job","tags":["Game Data"]}},"/relics":{"get":{"description":"Returns relic definitions with their stats, attributes, requirements (the craft recipe) and rendered GIF image. Without `id` it returns the full list; with `id` it returns the single matching relic object.","operationId":"get_relics","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Return only the relic with this id","in":"query","name":"id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"relics":[{"attributes":["DASH","NIGHT_VISION"],"id":"pineapple","image":"https://cdn2.minebox.co/data/mobs/skull_pineapple.gif","name":"Pineapple Skull","requirements":[{"level":10,"type":"player_level"},{"amount":4,"item":"mbi-pineapple","type":"item"}],"stats":{"endurance":25,"energy":25,"health":25,"luck":50}}],"total":10}}},"description":"Relic list (or a single relic when id is set)"},"404":{"description":"Relic not found (when id is set)"}},"summary":"List relics","tags":["Game Data"]}},"/sets":{"get":{"description":"Returns all equipment sets with translated names and bonus tiers.","operationId":"get_sets","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"sets":[{"bonuses":{"2":{"STRENGTH":5},"4":{"STRENGTH":15}},"id":"iron_set","name":"Iron Set"}],"total":20}}},"description":"Set list"}},"summary":"List all item sets","tags":["Items"]}},"/sets/{id}":{"get":{"description":"Returns full set details with translated name and stat bonuses per piece count.","operationId":"get_sets_id","parameters":[{"description":"Set ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"description":"Set details"},"404":{"description":"Set not found"}},"summary":"Get a set's details","tags":["Items"]}},"/ships":{"get":{"description":"Returns paginated ship data. Each ship exposes its brand, rarity, component slot layout (HULL/MAST/BOW/CANNON/CREW), player stat scopes, and a per-level progression list where each level declares its experience_required, speed, cargo and player_stats. Names are translated via the item i18n system. Sorting by speed uses the ship's max-level speed.","operationId":"get_ships","parameters":[{"description":"Language code","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Search by name or ID","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"Filter by brand (WOODY, OCEAN, LUXE, TECH)","in":"query","name":"brand","required":false,"schema":{"type":"string"}},{"description":"Filter by rarity","in":"query","name":"rarity","required":false,"schema":{"type":"string"}},{"description":"Sort key: rarity, nameAsc, nameDesc, speed (speed = max-level speed)","in":"query","name":"sort","required":false,"schema":{"default":"rarity","type":"string"}},{"description":"Page number","in":"query","name":"page","required":false,"schema":{"default":"1","type":"integer"}},{"description":"Items per page (max 50)","in":"query","name":"pageSize","required":false,"schema":{"default":"50","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"page":1,"pageSize":50,"ships":[{"brand":"OCEAN","component_slots":["HULL","HULL","MAST","CANNON","CANNON","BOW","CREW"],"id":"brigantine","images":[],"levels":[{"cargo":6,"experience_required":0,"level":1,"player_stats":{"luck":1},"speed":10},{"cargo":10,"experience_required":25000,"level":10,"player_stats":{"fortune":"5%","luck":3},"speed":30}],"model":"ship_brigantine","name":"Brigantine","player_stat_scopes":["all"],"rarity":"LEGENDARY"}],"total":8}}},"description":"Paginated list of ships"}},"summary":"List all ships","tags":["Game Data"]}},"/ships/{id}":{"get":{"description":"Returns full details for a single ship including translated name and lore, its component slot layout, player stat scopes, and the complete per-level progression (experience_required, speed, cargo, player_stats).","operationId":"get_ships_{id}","parameters":[{"description":"Ship ID (e.g. brigantine)","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Language code","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"brand":"OCEAN","component_slots":["HULL","HULL","MAST","CANNON","CANNON","BOW","CREW"],"id":"brigantine","images":[],"levels":[{"cargo":6,"experience_required":0,"level":1,"player_stats":{"luck":1},"speed":10},{"cargo":10,"experience_required":25000,"level":10,"player_stats":{"fortune":"5%","luck":3},"speed":30}],"lore":"Fast enough to escape, but slow enough to regret picking a fight with pirates.","model":"ship_brigantine","name":"Brigantine","player_stat_scopes":["all"],"rarity":"LEGENDARY"}}},"description":"Ship details"},"404":{"description":"Ship not found"}},"summary":"Get ship details","tags":["Game Data"]}},"/shops":{"get":{"description":"Returns NPC shop items with their buy/sell prices, stock, category, and icons.","operationId":"get_shops","parameters":[{"description":"Filter by shop category (ores, farm, fishes, insects, loots, blocks, plants, trash)","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Search by item ID","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"buy_price":120,"category":"ores","icon":"data:image/png;base64,...","id":"material-redstone","sell_price":24,"stock":1280}],"total":120}}},"description":"List of shop items"}},"summary":"List all shop items with prices","tags":["Game Data"]}},"/skills":{"get":{"description":"Returns all skills/professions with translated names, the XP required per level (experience_per_level), the XP granted per action (xp_rewards: harvestables/mobs/blocks/entities), and the default craft XP per recipe ingredient count (craft_experience, keyed 1..7). Action rewards scale linearly from `from` (level 1) to `to` (at `to_level`), flat when `to` == `from`. Craft XP scales from `start` down to `end` at `max_level`; a recipe may override it on /recipes, otherwise effective = recipe.experience ?? craft_experience[len(ingredients)].","operationId":"get_skills","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"skills":[{"craft_experience":{"1":{"end":5,"max_level":60,"start":75}},"experience_per_level":[100,250,500],"id":"miner","name":"Mining","xp_rewards":{"harvestables":{"coal":{"from":20,"to":10,"to_level":20}}}}],"total":13}}},"description":"Skill list"}},"summary":"List all skills","tags":["Game Data"]}},"/spells":{"get":{"description":"Returns spells granted by the given class with translated names, icons, and damage info — including spells unlocked by level, the passive-slot spell, and the auto-attack spell. The `class` query parameter is required. Each spell carries a `class_id` pointing to the class that grants it (derived from `spell_unlocks`, `passive`, and `auto_attack`).","operationId":"get_spells","parameters":[{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}},{"description":"Class ID (e.g. mage, archer)","in":"query","name":"class","required":true,"schema":{"type":"string"}},{"description":"Search by name (case-insensitive)","in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"spells":[{"class_id":"mage","icon":"data:image/png;base64,...","id":"fireball","name":"Fireball"}],"total":40}}},"description":"Spell list"}},"summary":"List spells for a class","tags":["Game Data"]}},"/spells/batch":{"get":{"description":"Returns a map of spell ID to spell details for the requested IDs. Maximum 50 IDs per request.","operationId":"get_spells_batch","parameters":[{"description":"Comma-separated spell IDs (max 50)","in":"query","name":"ids","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fireball":{"class_id":"mage","id":"fireball","name":"Fireball"}}}},"description":"Map of spell ID to spell details"},"400":{"description":"Missing or too many IDs"}},"summary":"Get multiple spells by ID","tags":["Game Data"]}},"/spells/{id}":{"get":{"description":"Returns full spell details with translated name, damages, and icon. Includes `class_id` pointing to the parent class.","operationId":"get_spells_id","parameters":[{"description":"Spell ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Locale for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"description":"Spell details"},"404":{"description":"Spell not found"}},"summary":"Get a spell's details","tags":["Game Data"]}},"/village":{"get":{"description":"","operationId":"get_village","responses":{"200":{"description":"Village configuration including tiers, buildings, requirements and cells"}},"summary":"Get Village","tags":["Game Data"]}},"/votes":{"get":{"description":"","operationId":"get_votes","responses":{"200":{"description":"Available vote websites with cooldown settings"}},"summary":"List vote websites","tags":["Votes"]}},"/votes/{username}":{"get":{"description":"Returns when the player can next vote on each website.","operationId":"get_votes_username","parameters":[{"description":"Minecraft username","in":"path","name":"username","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Map of website name to next available vote time"},"404":{"content":{"application/json":{"example":{"error":"User not found"}}},"description":"User not found"}},"summary":"Get a player's vote cooldowns","tags":["Votes"]}},"/zones":{"get":{"description":"Returns every server zone (spawn and exploration islands) with its translated title and description.","operationId":"get_zones","parameters":[{"description":"Locale code for translations","in":"query","name":"locale","required":false,"schema":{"default":"en","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"total":6,"zones":[{"id":"spawn","name":"Spawn island (/spawn)"},{"id":"island_tropical","name":"Kokoko Island"}]}}},"description":"List of zones"}},"summary":"List all server zones","tags":["Game Data"]}}},"servers":[{"description":"Production","url":"https://api.minebox.co"}]}