{
  "openapi": "3.0.3",
  "info": {
    "title": "Hypixel API & BomboAPI Complete Interactive Reference",
    "description": "Comprehensive reference and interactive guide for the official **Hypixel API (v2)** and **BomboAPI** services. Features complete endpoint documentation, schemas, and live examples using player **`bomboclas`** (UUID: `e4523c8e-5215-4e35-9631-7ede320beee0`).",
    "version": "2.0.0",
    "contact": {
      "name": "BomboAPI Support",
      "url": "https://bombo.dpdns.org"
    }
  },
  "servers": [
    {
      "url": "https://api.bombo.dpdns.org",
      "description": "BomboAPI Direct Server (Includes All Hypixel, Coflnet & Custom Endpoints)"
    }
  ],
  "tags": [
    {
      "name": "🎮 Mod — BomboAddons Integrations",
      "description": "Endpoints specifically powering the BomboAddons client mod for Fabric/Forge (trade helper, kismet rerolls, hoppity chocolate factory, bestiary tracking, custom glowing highlights, kuudra stats, skull textures, and mod download updates)."
    },
    {
      "name": "👤 User & Account Management",
      "description": "Player identity portal, linked Discord and Minecraft account synchronizer, tracked playtime sessions, NameMC history, and visual explorer tools. Endpoints requiring user authentication are clearly marked."
    },
    {
      "name": "🏝️ SkyBlock Complete API",
      "description": "Complete Hypixel SkyBlock API: active profile data, networth calculation, museum item appraisals, bazaar orders, active & ended auctions, garden, firesales, election mayor votes, SkyBlock collections & skills resources, RTCA catacombs accelerator, inventory inspection, and interactive 3D Player Viewer."
    },
    {
      "name": "🌐 Hypixel Full API",
      "description": "Official Hypixel Public API (v2) network & games: player stats, online status, guilds, recent games, network player counts, leaderboards, punishment statistics, network boosters, official games & achievements resources, and live server ping. Requests proxied through BomboAPI automatically include authentication without requiring an API key."
    },
    {
      "name": "📈 Coflnet & Market Analytics",
      "description": "SkyCofl / Coflnet real-time auction house history, player bids, active listings, crafting recipes, bazaar price trends, graphs, AI predictions, and item data."
    },
    {
      "name": "⚙️ API Keys & Administration",
      "description": "Administrative management portal, deterministic API key issuance, rate limit configuration, custom suspension motives, and security audit logs. **All management routes strictly require Admin Login or authorized session.**"
    }
  ],
  "paths": {
    "/v2/player": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Player Statistics",
        "description": "Retrieves comprehensive statistics for a Hypixel player across all games (Bedwars, Skywars, Duels, Arcade, Network Level, Karma, Achievements, etc.).",
        "parameters": [
          {
            "name": "uuid",
            "in": "query",
            "required": true,
            "description": "Player UUID (32-character hex or formatted with dashes). Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "description": "Hypixel API Key (automatically handled if querying through BomboAPI)",
            "schema": {
              "type": "string",
              "default": "YOUR_API_KEY_HERE"
            },
            "example": "YOUR_API_KEY_HERE"
          }
        ],
        "responses": {
          "200": {
            "description": "Hypixel player statistics JSON object"
          }
        }
      }
    },
    "/v2/status": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Player Online Status",
        "description": "Retrieves current online status, game mode, map, and lobby for a specific player.",
        "parameters": [
          {
            "name": "uuid",
            "in": "query",
            "required": true,
            "description": "Player UUID",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Player session and status response"
          }
        }
      }
    },
    "/v2/guild": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Guild Data (by Player UUID / IGN, Guild Name, or Guild ID)",
        "description": "**Authentication:** Public (Proxied with server key).\n\nRetrieves guild details, members, member ranks, and guild experience. Accepts player UUID or Minecraft IGN (`bomboclas`), guild name (`Skyblock Tilines`), or internal guild ID (`646a7f7c8ea8c9051b184c4b`). If called without query parameters, it automatically defaults to `bomboclas`'s active guild.",
        "parameters": [
          {
            "name": "player",
            "in": "query",
            "required": false,
            "description": "Player UUID or username in the guild (e.g. `bomboclas` or `e4523c8e52154e3596317ede320beee0`).",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Guild name (e.g. `Skyblock Tilines`).",
            "schema": {
              "type": "string"
            },
            "example": "Skyblock Tilines"
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Hypixel 24-character Guild ObjectId (e.g. `646a7f7c8ea8c9051b184c4b`).",
            "schema": {
              "type": "string"
            },
            "example": "646a7f7c8ea8c9051b184c4b"
          }
        ],
        "responses": {
          "200": {
            "description": "Guild data response"
          }
        }
      }
    },
    "/v2/recentgames": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Recent Games Played",
        "description": "Retrieves up to 100 recent games played by a player (gameType, mode, map, date/time, and duration).",
        "parameters": [
          {
            "name": "uuid",
            "in": "query",
            "required": true,
            "description": "Player UUID",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Recent games list"
          }
        }
      }
    },
    "/v2/counts": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Network Player Counts",
        "description": "Retrieves live player counts across the entire Hypixel Network, broken down by game type and mode.",
        "responses": {
          "200": {
            "description": "Network player counts object"
          }
        }
      }
    },
    "/v2/leaderboards": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Network Leaderboards",
        "description": "Retrieves official leaderboards across all Hypixel games.",
        "responses": {
          "200": {
            "description": "Leaderboards data"
          }
        }
      }
    },
    "/v2/punishmentstats": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Punishment Statistics",
        "description": "Retrieves total Watchdog bans, staff bans, and rolling daily ban counts.",
        "responses": {
          "200": {
            "description": "Watchdog and staff punishment statistics"
          }
        }
      }
    },
    "/v2/boosters": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Network Boosters",
        "description": "Retrieves all currently active and queued network boosters.",
        "responses": {
          "200": {
            "description": "Boosters list"
          }
        }
      }
    },
    "/v2/skyblock/profiles": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get All SkyBlock Profiles for Player",
        "description": "Retrieves all SkyBlock profiles belonging to a player (active, co-op members, banking, inventories, skills, slayers, dungeons, etc.).",
        "parameters": [
          {
            "name": "uuid",
            "in": "query",
            "required": true,
            "description": "Player UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "SkyBlock profiles array"
          }
        }
      }
    },
    "/v2/skyblock/profile": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Single SkyBlock Profile",
        "description": "Retrieves a single SkyBlock profile by player UUID or profile ID.",
        "parameters": [
          {
            "name": "profile",
            "in": "query",
            "required": false,
            "description": "SkyBlock Profile ID or username. Defaults to bomboclas profile.",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          },
          {
            "name": "uuid",
            "in": "query",
            "required": false,
            "description": "Player UUID or username (e.g. bomboclas).",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Single SkyBlock profile data"
          }
        }
      }
    },
    "/v2/skyblock/museum": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Museum Items",
        "description": "Retrieves museum data, donated weapons, armor sets, and special items for a SkyBlock profile.",
        "parameters": [
          {
            "name": "profile",
            "in": "query",
            "required": false,
            "description": "SkyBlock Profile UUID or player username (e.g. bomboclas). If omitted, defaults to bomboclas profile.",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Museum data object"
          }
        }
      }
    },
    "/v2/skyblock/garden": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Garden Data",
        "description": "Retrieves Garden crop milestones, plot states, compost, copper, and visitor serving records.",
        "parameters": [
          {
            "name": "profile",
            "in": "query",
            "required": false,
            "description": "SkyBlock Profile UUID or player username (e.g. bomboclas). If omitted, defaults to bomboclas profile.",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Garden data object"
          }
        }
      }
    },
    "/v2/skyblock/bazaar": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Bazaar Data",
        "description": "Retrieves live Bazaar marketplace data, buy/sell summary orders, quick status (buyPrice, sellPrice, volume), and 7-day moving averages for all tradeable items.",
        "responses": {
          "200": {
            "description": "Live Bazaar products dictionary"
          }
        }
      }
    },
    "/v2/skyblock/auctions": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Active SkyBlock Auctions",
        "description": "Retrieves active auctions on the SkyBlock Auction House (paged).",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (0-indexed)",
            "schema": {
              "type": "integer"
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "Paged auctions list"
          }
        }
      }
    },
    "/v2/skyblock/auctions_ended": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Recently Ended Auctions",
        "description": "Retrieves recently completed/sold auctions from the past 60 seconds (useful for price tracking and transaction feeds).",
        "responses": {
          "200": {
            "description": "Recently ended auctions"
          }
        }
      }
    },
    "/v2/skyblock/items": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Item Database",
        "description": "Retrieves official SkyBlock item catalog containing base stats, rarity tiers, NPC sell prices, and category tags.",
        "responses": {
          "200": {
            "description": "Items list"
          }
        }
      }
    },
    "/v2/skyblock/firesale": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Active Fire Sales",
        "description": "Retrieves currently running and upcoming cosmetic Fire Sales with start dates, prices, and item quotas.",
        "responses": {
          "200": {
            "description": "Fire sales list"
          }
        }
      }
    },
    "/v2/skyblock/election": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Mayor & Election",
        "description": "Retrieves current Mayor, active perks, Minister, and ongoing election candidate voting tallies.",
        "responses": {
          "200": {
            "description": "Mayor and election status"
          }
        }
      }
    },
    "/v2/skyblock/news": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock News & Updates",
        "description": "Retrieves official SkyBlock forum news, patch notes, and update announcements.",
        "responses": {
          "200": {
            "description": "News feed list"
          }
        }
      }
    },
    "/v2/resources/games": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Games Resource",
        "description": "Static mapping of Hypixel game IDs, names, and modes.",
        "responses": {
          "200": {
            "description": "Games definition"
          }
        }
      }
    },
    "/v2/resources/achievements": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Get Achievements Resource",
        "description": "Complete list of one-time and tiered achievements across all game modes.",
        "responses": {
          "200": {
            "description": "Achievements list"
          }
        }
      }
    },
    "/v2/resources/skyblock/collections": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Collections",
        "description": "Collection tiers, requirements, and reward unlock definitions.",
        "responses": {
          "200": {
            "description": "Collections definition"
          }
        }
      }
    },
    "/v2/resources/skyblock/skills": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Skills",
        "description": "SkyBlock skill leveling curve, XP requirements, and bonus stats per level.",
        "responses": {
          "200": {
            "description": "Skills definition"
          }
        }
      }
    },
    "/v2/resources/skyblock/items": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Items Resource",
        "description": "SkyBlock item catalog resource definition.",
        "responses": {
          "200": {
            "description": "SkyBlock items definition"
          }
        }
      }
    },
    "/v2/resources/skyblock/election": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Mayor Resource",
        "description": "Mayor candidate metadata and perk descriptions.",
        "responses": {
          "200": {
            "description": "Mayor resource"
          }
        }
      }
    },
    "/v2/resources/skyblock/bingo": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Bingo Goals",
        "description": "Current Bingo event goal grid and milestone requirements.",
        "responses": {
          "200": {
            "description": "Bingo goals definition"
          }
        }
      }
    },
    "/nw/{username}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Calculate Player SkyBlock Networth",
        "description": "Computes accurate SkyBlock networth using SkyHelper pricing algorithms. Evaluates armor, weapons, accessories (talismans), pets, wardrobe, storage, and unborrowed museum items.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Networth breakdown with itemized valuations"
          }
        }
      }
    },
    "/nwc/{username}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Calculate Cooperative Networth",
        "description": "Computes total collective networth across all members in a player's SkyBlock co-op profile, including co-op bank balance.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Cooperative networth breakdown"
          }
        }
      }
    },
    "/museum/{username}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Player Museum Items & Valuation",
        "description": "Retrieves the parsed list of items stored in a player's SkyBlock Museum along with item appraisal status.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed museum items"
          }
        }
      }
    },
    "/rank/{username}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Formatted Player Rank",
        "description": "Retrieves a player's official Hypixel rank formatted with Minecraft color codes (`§b[MVP§c+§b]`) and clean unformatted text.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Formatted player rank"
          }
        }
      }
    },
    "/inventory/{username}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Inspect Player Inventory & Storage",
        "description": "Parses and decodes player active inventory, equipment, armor, and ender chest items with full NBT attributes.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Decoded inventory items"
          }
        }
      }
    },
    "/playtime/{username}": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Get Tracked Player Playtime",
        "description": "Retrieves lifetime tracked playtime, active time, AFK time, and sub-area time breakdown for a player.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Set to `json` for raw API response",
            "schema": {
              "type": "string"
            },
            "example": "json"
          }
        ],
        "responses": {
          "200": {
            "description": "Playtime breakdown response"
          }
        }
      }
    },
    "/name/{username}": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Get Player Name History & Changes",
        "description": "Retrieves full historical name changes from NameMC with exact UTC timestamps, accuracy windows, and hidden names.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Minecraft IGN or UUID. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Set to `json` for raw API response",
            "schema": {
              "type": "string"
            },
            "example": "json"
          }
        ],
        "responses": {
          "200": {
            "description": "Name history list with timestamps"
          }
        }
      }
    },
    "/price/{itemId}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Item Pricing",
        "description": "Retrieves real-time Bazaar buy/sell price and Auction House lowest BIN price for an item ID.",
        "parameters": [
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "description": "SkyBlock item ID (e.g. `HYPERION`, `TERMINATOR`, `BOOSTER_COOKIE`)",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Item price object"
          }
        }
      }
    },
    "/prices": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Aggregated Real-Time Item Prices [Public]",
        "description": "**Authentication:** Public (No login required)\n\nAggregated item market valuations computed from Auction Lowest BIN and Bazaar order books.",
        "responses": {
          "200": {
            "description": "Map of item IDs to calculated coin prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/calendar/events": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get SkyBlock Events & Schedule",
        "description": "Retrieves SkyBlock in-game calendar events, active timers, Spooky Festival, Jerry's Workshop, and Dark Auction schedules.",
        "responses": {
          "200": {
            "description": "Upcoming events schedule"
          }
        }
      }
    },
    "/alpha": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Hypixel Alpha Test Server Status [Public]",
        "description": "**Authentication:** Public (No login required)\n\nHypixel Alpha test network status: current player count, server capacity limit, and open/closed state.",
        "responses": {
          "200": {
            "description": "Alpha network capacity and status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/feast": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Harvest Feast Event Tracker [Public]",
        "description": "**Authentication:** Public (No login required)\n\nHarvest Feast festival schedule, active crop recipes, and food preparation countdown timers.",
        "responses": {
          "200": {
            "description": "Harvest feast status and crop schedule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/feast/current": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Current Harvest Feast Crops",
        "description": "Retrieves live crowd-sourced Harvest Feast crops for the current SkyBlock month and next rotation timestamps.",
        "responses": {
          "200": {
            "description": "Current crops array and next rotation timers"
          }
        }
      }
    },
    "/feast/rotations": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Harvest Feast Rotations Schedule",
        "description": "Retrieves all Harvest Feast crop rotation schedules for the current SkyBlock year.",
        "responses": {
          "200": {
            "description": "Rotations schedule dictionary"
          }
        }
      }
    },
    "/api/craft/recipe/{itemTag}": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Item Crafting Recipe & Cost",
        "description": "Retrieves the full crafting matrix/recipe, required ingredients, quantities, and real-time craft profit calculation for an item tag.",
        "parameters": [
          {
            "name": "itemTag",
            "in": "path",
            "required": true,
            "description": "SkyBlock item ID/tag. Example: `HYPERION`, `ASPECT_OF_THE_DRAGON`, `TERMINATOR`",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Crafting recipe structure with ingredients and cost breakdown",
            "content": {
              "application/json": {
                "example": {
                  "item": "HYPERION",
                  "cost": 1850000000,
                  "craftPrice": 1920000000,
                  "profit": 70000000,
                  "recipe": [
                    {
                      "slot": 1,
                      "item": "NECRON_HANDLE",
                      "count": 1
                    },
                    {
                      "slot": 4,
                      "item": "WITHER_SHIELD",
                      "count": 1
                    },
                    {
                      "slot": 7,
                      "item": "SHADOW_WARP",
                      "count": 1
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/item/price/{itemTag}/history/all": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Full Item Price History & Graph Data",
        "description": "Retrieves the complete historical price timeline and volume data across all recorded history for Auction House BIN and Bazaar, formatted for charting and graph rendering.",
        "parameters": [
          {
            "name": "itemTag",
            "in": "path",
            "required": true,
            "description": "SkyBlock item ID/tag. Example: `HYPERION`, `BOOSTER_COOKIE`, `ENCHANTED_PUMPKIN`",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of historical timestamped price points and volume",
            "content": {
              "application/json": {
                "example": [
                  {
                    "timestamp": "2026-08-01T00:00:00Z",
                    "avgPrice": 1820000000,
                    "volume": 12,
                    "lowestBin": 1799000000
                  },
                  {
                    "timestamp": "2026-08-15T00:00:00Z",
                    "avgPrice": 1860000000,
                    "volume": 15,
                    "lowestBin": 1845000000
                  },
                  {
                    "timestamp": "2026-09-01T00:00:00Z",
                    "avgPrice": 1910000000,
                    "volume": 9,
                    "lowestBin": 1899999999
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/item/price/{itemTag}/history/{range}": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Item Price History by Range (Graph Series)",
        "description": "Retrieves high-resolution price history and candlestick graph points for an item over a specified time window (`day`, `week`, `month`, `year`, `full`).",
        "parameters": [
          {
            "name": "itemTag",
            "in": "path",
            "required": true,
            "description": "SkyBlock item ID/tag. Example: `BOOSTER_COOKIE`",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          },
          {
            "name": "range",
            "in": "path",
            "required": true,
            "description": "Time range filter: `day`, `week`, `month`, `year`, or `full`",
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month",
                "year",
                "full"
              ]
            },
            "example": "week"
          }
        ],
        "responses": {
          "200": {
            "description": "Price history dataset for graph visualization"
          }
        }
      }
    },
    "/api/data/ai": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Market AI Predictions & Flip Insights",
        "description": "Fetches machine-learning powered market trend forecasts, price predictions, flipping margins, and anomaly detections across Bazaar and Auction House items.",
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Optional item tag filter (e.g. `DIVAN_DRILL`)",
            "schema": {
              "type": "string"
            },
            "example": "DIVAN_DRILL"
          }
        ],
        "responses": {
          "200": {
            "description": "AI analysis model predictions and projected target prices"
          }
        }
      }
    },
    "/api/items/bazaar/tags": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get All Bazaar Item Tags",
        "description": "Returns a comprehensive list of all active item tags, categories, and identifiers currently traded on the SkyBlock Bazaar.",
        "responses": {
          "200": {
            "description": "List of active Bazaar item tags",
            "content": {
              "application/json": {
                "example": [
                  "ENCHANTED_CARROT",
                  "RECOMBOBULATOR_3000",
                  "BOOSTER_COOKIE",
                  "SUMMONING_EYE",
                  "STOCK_OF_STONKS"
                ]
              }
            }
          }
        }
      }
    },
    "/api/items": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get All SkyBlock Item Definitions",
        "description": "Retrieves the full master database of all SkyBlock items with their display names, tiers/rarities, category, skin textures, NPC buy/sell values, and base stats.",
        "responses": {
          "200": {
            "description": "Array of item metadata definitions"
          }
        }
      }
    },
    "/api/kat/data": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Kat Pet Upgrade Costs & Data",
        "description": "Retrieves all pet upgrade levels, coin fees, required items, and duration times for upgrading pets via Kat the Pet Caretaker.",
        "responses": {
          "200": {
            "description": "Kat pet upgrade table and required materials"
          }
        }
      }
    },
    "/api/player/{uuid}/bids": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Player Auction Bid & Purchase History",
        "description": "Retrieves recent and historical bids placed by a player, including winning bids, outbid records, amounts, and auction timestamps.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "description": "Player UUID or Minecraft IGN. Example: `bomboclas` / `e4523c8e-5215-4e35-9631-7ede320beee0`",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "List of bids and purchase history for the player",
            "content": {
              "application/json": {
                "example": [
                  {
                    "auctionId": "73c6bbcf361b4fa0a6ff8bf54e95d034",
                    "itemName": "Hyperion",
                    "amount": 1890000000,
                    "timestamp": "2026-09-02T18:45:10Z",
                    "bidder": "bomboclas"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/player/{uuid}/auctions": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Player Full Auction Listing History",
        "description": "Retrieves lifetime and historical auction listings created by a player, including sold items, expired auctions, highest bidders, starting bids, and final sales prices.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "description": "Player UUID or Minecraft IGN. Example: `bomboclas` / `e4523c8e-5215-4e35-9631-7ede320beee0`",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of past and active auction records created by the player",
            "content": {
              "application/json": {
                "example": [
                  {
                    "uuid": "a7b8c9d0-1234-5678-90ab-cdef12345678",
                    "seller": "bomboclas",
                    "item_name": "Terminator ✪✪✪✪✪",
                    "starting_bid": 780000000,
                    "highest_bid_amount": 810000000,
                    "bin": true,
                    "start": "2026-08-28T14:20:00Z",
                    "end": "2026-08-28T20:20:00Z"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/player/names": {
      "post": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Resolve Batch UUIDs to Player Names",
        "description": "Resolves an array of Minecraft UUIDs into their corresponding in-game usernames in a single batch request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "example": [
                "e4523c8e-5215-4e35-9631-7ede320beee0",
                "4536e098-7295-4228-b04f-126392474f28"
              ]
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key-value mapping of UUIDs to username strings"
          }
        }
      }
    },
    "/api/player/{uuid}/bazaar/orders": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Player Tracked Bazaar Orders",
        "description": "Retrieves recorded buy orders and sell offers submitted by the specified player on the SkyBlock Bazaar.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "description": "Player UUID or Minecraft IGN. Example: `bomboclas`",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "List of historical and active Bazaar orders"
          }
        }
      }
    },
    "/api/price/nbt": {
      "post": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Calculate Appraisal Price from Custom NBT Data",
        "description": "Calculates the fair market appraisal value of an item based on its encoded NBT data, including stars, enchantments, master stars, reforge, gemstones, drill parts, and attributes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "nbt": {
                    "type": "string",
                    "description": "Base64 encoded gzipped NBT string"
                  }
                }
              },
              "example": {
                "nbt": "H4sIAAAAAAAAAONiYGBm4HzBwMDAzsDAAMb/GTgZGBj4wQIAq6a6hxoAAAA="
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item valuation breakdown with separate enchantment and base value attributes"
          }
        }
      }
    },
    "/api/networth": {
      "post": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Calculate Full Profile Networth via Coflnet Engine",
        "description": "Parses SkyBlock profile inventory and equipment blobs using the Coflnet valuation algorithm to calculate exact networth, purse, bank, museum, and chest valuations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "profile": "e4523c8e-5215-4e35-9631-7ede320beee0"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detailed networth appraisal and individual item itemizations"
          }
        }
      }
    },
    "/api/profile/{profileId}/items": {
      "get": {
        "tags": [
          "📈 Coflnet & Market Analytics"
        ],
        "summary": "Get Decoded Profile Items & Storage",
        "description": "Retrieves the parsed and priced inventory, wardrobe, accessory bag, ender chest, and pet storage for a specific SkyBlock profile UUID.",
        "parameters": [
          {
            "name": "profileId",
            "in": "path",
            "required": true,
            "description": "SkyBlock Profile UUID",
            "schema": {
              "type": "string",
              "default": "e4523c8e-5215-4e35-9631-7ede320beee0"
            },
            "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "Full item catalog and equipment of the profile"
          }
        }
      }
    },
    "/mod/latest": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Get Latest Mod Release Info [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves version number, download URL, release notes, and build hash of the latest released BomboAddons Minecraft mod.",
        "responses": {
          "200": {
            "description": "Latest mod version metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/download": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Download Latest Mod JAR [Public]",
        "description": "**Authentication:** Public (No login required)\n\nDirect download endpoint serving the latest production `.jar` build of BomboAddons.",
        "responses": {
          "200": {
            "description": "Binary JAR file stream",
            "content": {
              "application/java-archive": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/changelog": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Get Mod Changelog & History [Public]",
        "description": "**Authentication:** Public (No login required)\n\nComplete changelog history, feature changes, bug fixes, and patch notes across all released mod builds.",
        "responses": {
          "200": {
            "description": "Changelog text / markdown / JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/versions": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "List All Mod Releases [Public]",
        "description": "**Authentication:** Public (No login required)\n\nLists all historical mod builds with version numbers, commit hashes, and individual download links.",
        "responses": {
          "200": {
            "description": "Array of mod release objects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/version/{version}": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Download Specific Mod Version [Public]",
        "description": "**Authentication:** Public (No login required)\n\nDownloads a specific historical version `.jar` (e.g. `26.2.28.11`).",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "description": "Version string, e.g. `26.2.28.11`",
            "schema": {
              "type": "string",
              "default": "26.2.28.11"
            },
            "example": "26.2.28.11"
          }
        ],
        "responses": {
          "200": {
            "description": "Binary JAR file stream",
            "content": {
              "application/java-archive": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/trade": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "In-Game Trade Helper & Prices [Public]",
        "description": "**Authentication:** Public (No login required)\n\nEvaluates live item prices in player-to-player trades, calculating total coin valuation and estimated profit margins for trading items.",
        "responses": {
          "200": {
            "description": "Trade price evaluation and item list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/kismet/{player}": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Kismet Feather Reroll Tracker [Public]",
        "description": "**Authentication:** Public (No login required)\n\nTracks Kismet Feather reroll usage, dungeon loot statistics, and estimated reroll profitability for a player.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Kismet reroll metrics and chest stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/hoppity": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Hoppity Hunt & Chocolate Factory Data [Public]",
        "description": "**Authentication:** Public (No login required)\n\nHoppity Chocolate Factory egg spawn locations, active rabbit multipliers, and event state.",
        "responses": {
          "200": {
            "description": "Chocolate factory state and egg waypoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/bestiary": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "SkyBlock Bestiary Bracket & Tiers [Public]",
        "description": "**Authentication:** Public (No login required)\n\nSkyBlock mob kill thresholds, milestone bracket tiers, and family level definitions for the mod's Bestiary HUD.",
        "responses": {
          "200": {
            "description": "Bestiary family tiers and kill thresholds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/highlight": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Item Glowing & Highlight Rules [Public]",
        "description": "**Authentication:** Public (No login required)\n\nDynamic item glow, chest outline colors, and custom rarity highlight rules loaded by the in-game client.",
        "responses": {
          "200": {
            "description": "Item highlight rule configurations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mod/kuudra/{player}": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Kuudra Run Stats & Keys [Public]",
        "description": "**Authentication:** Public (No login required)\n\nKuudra boss completions by tier (Basic, Hot, Burning, Fiery, Infernal), key consumption, and crimson isle stats.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Kuudra tier completions and chest keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/tex/{textureId}": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Minecraft Head Skin & Texture Proxy [Public]",
        "description": "**Authentication:** Public (No login required)\n\nUltra-fast skull skin texture proxy for Minecraft custom head items rendered inside the mod GUI.",
        "parameters": [
          {
            "name": "textureId",
            "in": "path",
            "required": true,
            "description": "Mojang texture hash or custom skin ID",
            "schema": {
              "type": "string",
              "default": "e4523c8e52154e3596317ede320beee0"
            },
            "example": "e4523c8e52154e3596317ede320beee0"
          }
        ],
        "responses": {
          "200": {
            "description": "PNG texture image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/texturepacks": {
      "get": {
        "tags": [
          "🎮 Mod — BomboAddons Integrations"
        ],
        "summary": "Hypixel Texture Pack Tracker [Public]",
        "description": "**Authentication:** Public (No login required)\n\nTracks official Hypixel server resource pack updates, asset diffs, hashes, and download links.",
        "responses": {
          "200": {
            "description": "Texture pack versions and asset diffs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/account": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "User Account Portal [Login Required]",
        "description": "**Authentication:** Requires User Login Session (Cookie: `account_session` or HTTP Basic Auth).\n\nUser account dashboard for viewing connected identities, linked Discord account, and personal API tokens.",
        "responses": {
          "200": {
            "description": "Account HTML dashboard",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/account/sync": {
      "post": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Synchronize Account Identities [Login Required]",
        "description": "**Authentication:** Requires User Login Session.\n\nSynchronizes connected Discord credentials and linked Minecraft accounts across the user account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "discord_id": {
                    "type": "string"
                  },
                  "mc_name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sync success confirmation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/playtime/{player}": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Get Player Tracked Playtime [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves total tracked Hypixel SkyBlock playtime, session hours, active streaks, and AFK time for a player.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Playtime statistics and session data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/playtimes": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Playtime Leaderboard [Public]",
        "description": "**Authentication:** Public (No login required)\n\nGlobal server leaderboard of all tracked players ranked by total playtime hours.",
        "responses": {
          "200": {
            "description": "Ranked playtime leaderboard",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/playtime": {
      "post": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Record Playtime Heartbeat [Mod / API Key Required]",
        "description": "**Authentication:** Requires Mod API Key (Header: `x-api-key` or `Api-Key`).\n\nSession heartbeat ping sent automatically by in-game mod client while player is active on Hypixel.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ign": {
                    "type": "string",
                    "example": "bomboclas"
                  },
                  "session_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Heartbeat acknowledged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/name/{player}": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Mojang Username History & UUID [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves Mojang player name history, past name change timestamps, and formatted UUID.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player username or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Username history list and UUID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/commands": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "BomboBot Bridge Command Directory [Public]",
        "description": "**Authentication:** Public (No login required)\n\nComplete documentation and interactive guide of all BomboBot Discord slash commands and in-game `!` chat bridge commands.",
        "responses": {
          "200": {
            "description": "Commands reference guide HTML",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/visor": {
      "get": {
        "tags": [
          "👤 User & Account Management"
        ],
        "summary": "Visual SkyBlock API Explorer [Public]",
        "description": "**Authentication:** Public (No login required)\n\nInteractive visual explorer tool for querying, debugging, and inspecting Hypixel SkyBlock API payloads.",
        "responses": {
          "200": {
            "description": "Visor Explorer UI",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Selected SkyBlock Profile Data [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves complete active SkyBlock profile data including skill levels, slayer progression, dungeons, and equipment.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive profile data object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/{player}/profile/{name}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Profile by Cute Name [Public]",
        "description": "**Authentication:** Public (No login required)\n\nFetches a specific SkyBlock profile by its cute fruit name (e.g. `Orange`, `Kiwi`, `Apple`).",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "Cute profile name (e.g. `Orange`)",
            "schema": {
              "type": "string",
              "default": "Orange"
            },
            "example": "Orange"
          }
        ],
        "responses": {
          "200": {
            "description": "Specific SkyBlock profile data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/{player}/rtca": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Catacombs RTCA Accelerator [Public]",
        "description": "**Authentication:** Public (No login required)\n\nReal-Time Catacombs Accelerator (RTCA) calculation: computes dungeon runs required to reach target Catacombs level with class boosts.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "RTCA dungeon calculations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/nw/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Player SkyBlock Networth [Public]",
        "description": "**Authentication:** Public (No login required)\n\nCalculates accurate total networth, purse, bank, armor, equipment, pets, slayer, and storage valuation.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Networth breakdown object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/nwc/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Compact Networth Summary [Public]",
        "description": "**Authentication:** Public (No login required)\n\nCompact networth output formatted for bots and chat bridges (total networth, purse, bank in readable `7.6B` format).",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Compact networth text / JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/museum/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Player Museum Appraisals [Public]",
        "description": "**Authentication:** Public (No login required)\n\nLists all donated Museum items, special item valuations, armor sets, and total museum networth.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Museum items and total appraisal value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/rank/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Player Network Rank & Prefix [Public]",
        "description": "**Authentication:** Public (No login required)\n\nFetches Hypixel rank, plus color, staff/creator status, and colored display prefix.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Rank details and formatted prefix",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/inv/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Formatted Inventory & Wardrobe [Public]",
        "description": "**Authentication:** Public (No login required)\n\nDecoded inventory items, active armor slots, wardrobe sets, and ender chest storage contents.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed inventory slots and item NBT",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/pv/{player}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Interactive Player Viewer UI [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRich web-based SkyBlock Player Viewer: 3D player skin rendering, equipped armor, talismans, pets, skills, and gear stats.",
        "parameters": [
          {
            "name": "player",
            "in": "path",
            "required": true,
            "description": "Player IGN or UUID (e.g. `bomboclas`)",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Player Viewer interactive HTML page",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/pv-snapshot": {
      "post": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Load PV from JSON Snapshot [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRenders the interactive Player Viewer using a previously exported JSON profile snapshot file.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Player Viewer interactive HTML page",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/bazaar": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Live Bazaar Market Data [Public]",
        "description": "**Authentication:** Public (No login required)\n\nReal-time Hypixel Bazaar data: buy and sell order books, instant buy/sell prices, and 7-day moving volume.",
        "responses": {
          "200": {
            "description": "Bazaar market snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/items": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Complete Item Database [Public]",
        "description": "**Authentication:** Public (No login required)\n\nFull Hypixel SkyBlock items database including lore, tier, rarity, internal ID, and base stats.",
        "responses": {
          "200": {
            "description": "Array of all SkyBlock items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/item": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Get Single Item by ID [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves specs, stats, and recipes for a specific item using `?id={itemId}`.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "SkyBlock internal item ID (e.g. `HYPERION`, `NECRON_CHESTPLATE`)",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed item specification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/npcprices": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "NPC Merchant Buy & Sell Rates [Public]",
        "description": "**Authentication:** Public (No login required)\n\nOfficial Hypixel NPC merchant buy and sell values for all sellable game items.",
        "responses": {
          "200": {
            "description": "Map of item IDs to NPC coin values",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/bi": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Community Shop Bits Value & Efficiency [Public]",
        "description": "**Authentication:** Public (No login required)\n\nCalculates coin valuation and coins-per-bit efficiency for all Community Shop Bits items.",
        "responses": {
          "200": {
            "description": "Bits item rankings and coin-per-bit value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/craft/{id}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Item Crafting Tree & Costs [Public]",
        "description": "**Authentication:** Public (No login required)\n\nItem crafting recipe tree, component materials, and total craft cost estimation.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Item ID (e.g. `TERMINATOR`)",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Crafting tree and ingredient costs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/auction/{id}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Historical Auction & Coflnet Lookup [Public]",
        "description": "**Authentication:** Public (No login required)\n\nHistorical auction house sales records, median sales price, and Coflnet lookup for an item.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Item ID or Auction UUID",
            "schema": {
              "type": "string",
              "default": "HYPERION"
            },
            "example": "HYPERION"
          }
        ],
        "responses": {
          "200": {
            "description": "Auction sales history and price trend",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/decode-nbt": {
      "post": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Decode Minecraft NBT Data [Public]",
        "description": "**Authentication:** Public (No login required)\n\nDecodes base64-encoded, gzip-compressed Minecraft item NBT data into clean, structured JSON.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "string",
                    "description": "Base64 gzip NBT string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parsed JSON NBT structure",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/calendar": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Live SkyBlock Calendar & Event Timers [Public]",
        "description": "**Authentication:** Public (No login required)\n\nLive SkyBlock calendar schedule: seasons, Jerry's Workshop, Spooky Festival, Dark Auction, and custom event timers. Supports `?format=json` or HTML view.",
        "responses": {
          "200": {
            "description": "Calendar events and schedule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/election": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "SkyBlock Mayor & Election Polls [Public]",
        "description": "**Authentication:** Public (No login required)\n\nCurrent active SkyBlock Mayor, active perks, minister, and real-time election candidate votes.",
        "responses": {
          "200": {
            "description": "Mayor perks and election candidate data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/general": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "SkyBlock General Metadata & News [Public]",
        "description": "**Authentication:** Public (No login required)\n\nHypixel SkyBlock general election metadata, active global buffs, and news announcements.",
        "responses": {
          "200": {
            "description": "General SkyBlock metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/greenhouse": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Greenhouse Mutations Guide [Public]",
        "description": "**Authentication:** Public (No login required)\n\nSkyBlock Greenhouse mutations guide: crop cross-breeding combinations, seed tiers, and unlock requirements.",
        "responses": {
          "200": {
            "description": "Greenhouse crop mutation matrix",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/pet/{skill}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Pet XP Milestones & Skill Multipliers [Public]",
        "description": "**Authentication:** Public (No login required)\n\nPet XP leveling requirements, milestone brackets, and skill boost multipliers.",
        "parameters": [
          {
            "name": "skill",
            "in": "path",
            "required": true,
            "description": "Skill type, e.g. `COMBAT`, `MINING`, `FORAGING`, `FARMING`, `FISHING`, `ENCHANTING`, `ALCHEMY`",
            "schema": {
              "type": "string",
              "default": "COMBAT"
            },
            "example": "COMBAT"
          }
        ],
        "responses": {
          "200": {
            "description": "Pet XP requirements and leveling table",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mc/{ip}": {
      "get": {
        "tags": [
          "🌐 Hypixel Full API"
        ],
        "summary": "Live Minecraft Server Status [Public]",
        "description": "**Authentication:** Public (No login required)\n\nPings any Minecraft server IP to retrieve real-time online status, latency, player count, and MOTD banner.",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "description": "Server IP address or hostname (e.g. `mc.hypixel.net`)",
            "schema": {
              "type": "string",
              "default": "mc.hypixel.net"
            },
            "example": "mc.hypixel.net"
          }
        ],
        "responses": {
          "200": {
            "description": "Minecraft server ping and MOTD",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/hyp/{endpoint}": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "SkyBlock & Hypixel API Proxy (e.g. /hyp/skyblock/news)",
        "description": "**Authentication:** Public (Authentication handled automatically by BomboAPI proxy).\n\nDirect cached proxy to any official Hypixel API endpoint (e.g. `/hyp/skyblock/news`).",
        "parameters": [
          {
            "name": "endpoint",
            "in": "path",
            "required": true,
            "description": "Hypixel / SkyBlock endpoint path (e.g. `skyblock/news`, `skyblock/bazaar`, `player?uuid=...`)",
            "schema": {
              "type": "string",
              "default": "skyblock/news"
            },
            "example": "skyblock/news"
          }
        ],
        "responses": {
          "200": {
            "description": "Hypixel API response payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/keys": {
      "get": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "API Keys Dashboard [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session (Cookie: `admin_session`).\n\nWeb dashboard for managing all API keys, viewing real-time call counts, configuring rate limits, and suspending keys with custom motive reasons.",
        "responses": {
          "200": {
            "description": "Keys management dashboard HTML",
            "content": {
              "text/html": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/player": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Get/Create In-Game Key [Bot / Client Auth]",
        "description": "**Authentication:** Requires BomboBot Secret or In-Game Client identity.\n\nDeterministic API key lookup/creation for player Minecraft accounts and Discord IDs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mc_name": {
                    "type": "string",
                    "example": "bomboclas"
                  },
                  "mc_uuid": {
                    "type": "string",
                    "example": "e4523c8e-5215-4e35-9631-7ede320beee0"
                  },
                  "discord_id": {
                    "type": "string",
                    "example": "579709526903619596"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "API key object and status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/create": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Create API Key [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nGenerates a new API key with custom name, rate limits, and linked accounts.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Trade Bot Key"
                  },
                  "mc_name": {
                    "type": "string"
                  },
                  "discord_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created key object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/unlink_account": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Unlink Account from Key [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nRemoves a specific Minecraft account (IGN or UUID) from an existing API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "account"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Key ID or raw key"
                  },
                  "account": {
                    "type": "string",
                    "description": "Minecraft IGN or UUID to remove"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Remaining accounts after unlinking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/toggle": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Suspend / Stop Key with Motive [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nToggles an API key between active and suspended status with a custom motive reason string displayed to the suspended client.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "motive": {
                    "type": "string",
                    "example": "Rate limit abuse / excessive spam"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key toggle confirmation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/set_limits": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Configure Rate Limits [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nSets custom per-minute and per-hour request rate limits for an API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "min",
                  "hour"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "min": {
                    "type": "integer",
                    "example": 120
                  },
                  "hour": {
                    "type": "integer",
                    "example": 1000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Limit configuration result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/toggle_bridge": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Toggle Bridge Chat Permission [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nToggles bridge chat access permission for an API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bridge access toggle result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/delete": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Permanently Revoke Key [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nPermanently deletes an API key and records revocation motive.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "motive": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key deletion confirmation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/link": {
      "post": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Link Discord or Minecraft to Key [Public / Mod]",
        "description": "**Authentication:** Public / Mod Client.\n\nLinks a Discord ID or Minecraft IGN to an existing valid API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "discord_id": {
                    "type": "string"
                  },
                  "mc_name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/list": {
      "get": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "List All API Keys [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nLists all registered API keys with active status, rate limits, request counts, and linked player accounts.",
        "responses": {
          "200": {
            "description": "Array of registered API key records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/logs": {
      "get": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Get Key Audit Logs [Admin Login Required]",
        "description": "**Authentication:** Requires Admin Login Session.\n\nAudit history logs of recent requests, client IPs, endpoints, and timestamps for a specific API key.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Raw API key or Key ID",
            "schema": {
              "type": "string",
              "default": "YOUR_API_KEY_HERE"
            },
            "example": "YOUR_API_KEY_HERE"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit logs array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys/callstats/{id}": {
      "get": {
        "tags": [
          "⚙️ API Keys & Administration"
        ],
        "summary": "Recent Key Call Velocity Statistics",
        "description": "Returns real-time call frequency metrics (`last5m` and `last60m`) used by the dashboard tooltip to monitor active API traffic. The `{id}` path parameter can be a Key ID (e.g. `83ce2c18b0689314`), player Minecraft username (e.g. `bomboclas`), or player UUID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "API Key ID (e.g. `83ce2c18b0689314`), Minecraft username (`bomboclas`), or UUID.",
            "schema": {
              "type": "string",
              "default": "bomboclas"
            },
            "example": "bomboclas"
          }
        ],
        "responses": {
          "200": {
            "description": "Recent request count statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "last5m": {
                      "type": "integer",
                      "example": 0
                    },
                    "last60m": {
                      "type": "integer",
                      "example": 52
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/kat": {
      "get": {
        "tags": [
          "🏝️ SkyBlock Complete API"
        ],
        "summary": "Kat Pet Upgrade Database & Costs [Public]",
        "description": "**Authentication:** Public (No login required)\n\nRetrieves the full database of Kat Pet upgrades: coins, materials, and time required for all pet rarity tier upgrades.",
        "responses": {
          "200": {
            "description": "Full array of Kat upgrade recipes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    },
    "/weather": {
      "get": {
        "tags": [
          "🌦️ Weather & External Utilities"
        ],
        "summary": "Real-time Weather Forecast & Observation (AEMET)",
        "description": "Returns detailed weather forecasts, current sky conditions, minimum/maximum temperature, thermal sensation, wind speed/direction, rain probabilities, humidity, UV index, and multi-day forecast for any city, town, or municipality in Spain via the official **AEMET OpenData** network.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "City name, municipality, or 5-digit municipality code (e.g. `madrid`, `barcelona`, `valencia`, `sevilla`, `28079`). Defaults to Madrid if omitted.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "Madrid",
              "example": "Madrid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful weather forecast retrieval from AEMET.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "location": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "example": "28079"
                        },
                        "name": {
                          "type": "string",
                          "example": "Madrid"
                        },
                        "province": {
                          "type": "string",
                          "example": "Madrid"
                        }
                      }
                    },
                    "current": {
                      "type": "object"
                    },
                    "forecast": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "source": {
                      "type": "string",
                      "example": "AEMET (Agencia Estatal de Meteorología)"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}