{"openapi":"3.1.0","info":{"title":"Hydro Vanilla SMP API","version":"1.0.0","summary":"Public read-only access to Hydro Vanilla SMP player statistics.","description":"Public, read-only, unauthenticated access to the same statistics that power\nhttps://stats.hydrosmp.com — leaderboards for 217 tracked statistics, player\nprofiles, advancement progress, the crown hall of fame and weekly events.\n\nBuilt for Hydro members writing Discord bots, overlays and community tools.\nRate limit: 240 requests per minute per IP address.","contact":{"name":"Hydro Vanilla SMP Discord","url":"https://discord.gg/WbefzQ3nT9"},"license":{"name":"Free for non-commercial community use, with attribution","url":"https://api.hydrosmp.com/#terms"}},"servers":[{"url":"https://api.hydrosmp.com","description":"Production"}],"externalDocs":{"description":"Full documentation","url":"https://api.hydrosmp.com/"},"tags":[{"name":"Meta","description":"Discovery, health and server information."},{"name":"Statistics","description":"The stat catalogue, leaderboards, totals and advancement rarity."},{"name":"Players","description":"Player lookup, stats and advancements."},{"name":"Community","description":"Hall of fame and weekly events."},{"name":"Server","description":"What the server runs: mods and the optional modpack."},{"name":"Fun","description":"Comparisons and randomised picks for bot commands."},{"name":"Embeds","description":"SVG badges and cards for signatures, READMEs and Discord."}],"paths":{"/v1":{"get":{"tags":["Meta"],"summary":"API index","description":"Machine-readable list of every available endpoint.","operationId":"getIndex","responses":{"200":{"description":"The endpoint index.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/status":{"get":{"tags":["Meta"],"summary":"Live server status","description":"Queries the game server directly with a Server List Ping. Returns whether it is up, the current player count, the running version and the MOTD, plus the short random player sample the server itself publishes. Cached for 10 seconds.","operationId":"getStatus","responses":{"200":{"description":"Live status. `online: false` means the ping failed; the request still succeeds.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/health":{"get":{"tags":["Meta"],"summary":"Service health and data freshness","description":"Reports uptime and how long ago the statistics were last regenerated. Never cached.","operationId":"getHealth","responses":{"200":{"description":"Health report.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/server":{"get":{"tags":["Meta"],"summary":"Server information","description":"Addresses, player counts by edition, and the ranking rules used by the stats engine.","operationId":"getServer","responses":{"200":{"description":"Server information.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/stats":{"get":{"tags":["Statistics"],"summary":"List all tracked statistics","description":"The full catalogue, each with its unit, human title and current record holder.","operationId":"listStats","parameters":[{"name":"search","in":"query","description":"Case-insensitive filter on id, title or description.","schema":{"type":"string"},"example":"mine"},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The stat catalogue.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatList"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/stats/{stat_id}":{"get":{"tags":["Statistics"],"summary":"Leaderboard for one statistic","description":"Ordered ranking of every qualifying player for a single statistic.","operationId":"getLeaderboard","parameters":[{"name":"stat_id","in":"path","required":true,"description":"Statistic id from /v1/stats.","schema":{"type":"string"},"example":"jump"},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The leaderboard page.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leaderboard"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/totals":{"get":{"tags":["Statistics"],"summary":"Server-wide totals","description":"Every statistic summed across all ranked players, with the per-player average. Good for milestone posts.","operationId":"getTotals","parameters":[{"name":"search","in":"query","description":"Case-insensitive filter on stat id or title.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Server-wide totals.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/advancements":{"get":{"tags":["Statistics"],"summary":"Advancement catalogue with rarity","description":"Every advancement seen on the server, with how many players hold it and how rare that makes it. Sorted rarest first by default. Datapack bookkeeping entries are excluded unless asked for.","operationId":"listAdvancements","parameters":[{"name":"search","in":"query","description":"Case-insensitive filter on id or title.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Restrict to one category, e.g. nether, end, husbandry, adventure, story.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order. 'first' orders by who was earned on the server earliest.","schema":{"type":"string","enum":["rarity","title","category","first"],"default":"rarity"}},{"name":"include","in":"query","description":"Set to 'datapack' to also include datapack bookkeeping entries every player holds.","schema":{"type":"string","enum":["datapack","all"]}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The advancement catalogue.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancementList"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/advancements/{advancement_id}":{"get":{"tags":["Statistics"],"summary":"One advancement","description":"The namespace may be omitted; `story/mine_diamond` resolves to `minecraft:story/mine_diamond`.","operationId":"getAdvancement","parameters":[{"name":"advancement_id","in":"path","required":true,"schema":{"type":"string"},"example":"minecraft:nether/all_effects"}],"responses":{"200":{"description":"The advancement.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/advancements/{advancement_id}/holders":{"get":{"tags":["Statistics"],"summary":"Everyone holding one advancement","description":"Ordered by when each player earned it, oldest first — so position 1 is the first player on the server to get there.","operationId":"listAdvancementHolders","parameters":[{"name":"advancement_id","in":"path","required":true,"schema":{"type":"string"},"example":"minecraft:end/kill_dragon"},{"name":"order","in":"query","description":"'first' for the earliest earners, 'latest' for the most recent.","schema":{"type":"string","enum":["first","latest"],"default":"first"}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The holders, in order.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/feed":{"get":{"tags":["Community"],"summary":"Recent advancement unlocks","description":"Server-wide \"who just earned what\", newest first. Built for activity widgets and Discord bots.\n\nOnly real (vanilla) advancements appear — datapacks file their own bookkeeping as advancements and every player holds those.\nThe feed is a bounded tail of the most recent unlocks, not the full archive; `meta.feed_window` says how many events it covers and `meta.oldest_in_feed` where it stops.","operationId":"getFeed","parameters":[{"name":"player","in":"query","description":"Restrict to one player (UUID or exact name).","schema":{"type":"string"}},{"name":"category","in":"query","description":"Restrict to one category, e.g. nether, end, adventure.","schema":{"type":"string"}},{"name":"since","in":"query","description":"Only unlocks at or after this time — ISO 8601 or epoch seconds.","schema":{"type":"string"},"example":"2026-08-01T00:00:00Z"},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The unlock feed.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/history":{"get":{"tags":["Meta"],"summary":"Server population and progression over time","description":"How busy the server has been and how the roster has grown, sampled every few minutes.\n\nIncludes `hour_of_day`, the average concurrent players by local hour — the answer to \"when is Hydro busiest?\".\nHistory is **not** backfilled: nothing on the server recorded a time series before this endpoint existed, so the data starts at `meta.recording_since`.","operationId":"getHistory","parameters":[{"name":"resolution","in":"query","description":"Sample granularity. `raw` is the last 48 hours at full resolution.","schema":{"type":"string","enum":["raw","hourly","daily"],"default":"hourly"}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The requested series, plus the hour-of-day profile and all-time peak.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/activity":{"get":{"tags":["Community"],"summary":"Server-wide activity by hour and day","description":"How much the server is actually being played, reconstructed by diffing Minecraft's own playtime counters between stats pulls — a player whose `play_time` rose was online during that window.\n\n`hour_of_day` gives the average number of players online during a window starting in each local hour, which is the real answer to \"when is Hydro busy?\". `daily` gives active players, hours played and deaths per day.\n\nResolution is the stats-pull interval (15 minutes), and the data is not backfilled — it begins at `meta.recording_since`.","operationId":"getActivity","responses":{"200":{"description":"Server-wide activity.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/activity/players":{"get":{"tags":["Community"],"summary":"Most active players","description":"Per-player activity totals as a sortable leaderboard: hours played, sessions and deaths over the last 7 or 30 days, or since recording began.","operationId":"listActivePlayers","parameters":[{"name":"period","in":"query","description":"Window to total over.","schema":{"type":"string","enum":["7d","30d","all"],"default":"7d"}},{"name":"sort","in":"query","description":"What to rank by.","schema":{"type":"string","enum":["minutes","sessions","deaths"],"default":"minutes"}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The activity leaderboard.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players/{player}/activity":{"get":{"tags":["Players"],"summary":"One player's activity totals","description":"Hours played, sessions and deaths over the last 7 days, last 30 days and since recording began, plus where they rank against everyone else this week.\n\nTotals only. Per-session start and end times are deliberately never published — see the privacy note in the documentation. Lifetime playtime across the whole season is the `play` statistic.","operationId":"getPlayerActivity","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"}],"responses":{"200":{"description":"Activity totals. `active: false` when nothing has been recorded for them yet.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/badge/server.svg":{"get":{"tags":["Embeds"],"summary":"Live player count as an SVG badge","description":"A shields.io-style badge for a README, forum signature or site. Returns `image/svg+xml`, not JSON.","operationId":"getServerBadge","parameters":[{"name":"label","in":"query","description":"Left-hand label text.","schema":{"type":"string","default":"Hydro SMP"}},{"name":"color","in":"query","description":"Right-hand colour: a palette name (blue, green, amber, red, purple, pink, grey) or a hex value.","schema":{"type":"string"}}],"responses":{"200":{"description":"The badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/v1/badge/player/{player}.svg":{"get":{"tags":["Embeds"],"summary":"One player stat as an SVG badge","description":"Returns `image/svg+xml`, not JSON.\n\nErrors are also rendered as a badge (with the real HTTP status) rather than as JSON, so a broken embed still reads as an image.","operationId":"getPlayerBadge","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"},{"name":"stat","in":"query","description":"Any statistic id from /v1/stats, or one of: advancements, medals, rank.","schema":{"type":"string","default":"advancements"},"example":"play"},{"name":"label","in":"query","description":"Override the left-hand label (defaults to the player name).","schema":{"type":"string"}},{"name":"color","in":"query","description":"Right-hand colour: a palette name or a hex value.","schema":{"type":"string"}}],"responses":{"200":{"description":"The badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Rendered as an error badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Rendered as an error badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/v1/card/player/{player}.svg":{"get":{"tags":["Embeds"],"summary":"Shareable player stat card","description":"A larger card with playtime, advancements, hall-of-fame rank and medals. Returns `image/svg+xml`. Contains no avatar: this service has no outbound network access, and remote images are stripped by most embed sanitisers anyway.","operationId":"getPlayerCard","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"},{"name":"color","in":"query","description":"Accent colour: a palette name or a hex value.","schema":{"type":"string"}}],"responses":{"200":{"description":"The card.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Rendered as an error badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/v1/mods":{"get":{"tags":["Server"],"summary":"Server-side mods","description":"Every Fabric mod the server runs, resolved against Modrinth. Performance and quality-of-life only — none change Vanilla gameplay. Refreshed every few hours.","operationId":"listMods","parameters":[{"name":"search","in":"query","description":"Case-insensitive filter on slug or name.","schema":{"type":"string"}}],"responses":{"200":{"description":"The mod list.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/modpack":{"get":{"tags":["Server"],"summary":"The optional client modpack","description":"The Modrinth modpack players may install, including its latest version, supported Minecraft versions and download files. Never hardcoded — always read live from Modrinth.","operationId":"getModpack","responses":{"200":{"description":"The modpack.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/compare":{"get":{"tags":["Fun"],"summary":"Head-to-head player comparison","description":"Compares two players across every statistic either of them has, with a per-stat winner and an overall tally. One request is enough to render a versus embed.","operationId":"comparePlayers","parameters":[{"name":"players","in":"query","required":true,"description":"Exactly two comma-separated players (UUIDs or names).","schema":{"type":"string"},"example":"Phobia0,Blxde7"},{"name":"ids","in":"query","description":"Restrict the comparison to these comma-separated stat ids.","schema":{"type":"string"}}],"responses":{"200":{"description":"The comparison.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/random/player":{"get":{"tags":["Fun"],"summary":"A random ranked player","description":"Returns a random player who appears in the rankings, along with their single best rank. Never cached.","operationId":"getRandomPlayer","responses":{"200":{"description":"A random player.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/random/stat":{"get":{"tags":["Fun"],"summary":"A random statistic with its podium","description":"Returns a random statistic and its top three players — a daily-leaderboard bot in one call. Never cached.","operationId":"getRandomStat","responses":{"200":{"description":"A random statistic.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players":{"get":{"tags":["Players"],"summary":"List and search players","operationId":"listPlayers","parameters":[{"name":"search","in":"query","description":"Case-insensitive substring match on the player name.","schema":{"type":"string"}},{"name":"edition","in":"query","description":"Restrict to one client edition.","schema":{"type":"string","enum":["java","bedrock"]}},{"name":"ranked","in":"query","description":"Only players who have met the minimum playtime and appear in rankings.","schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Sort order.","schema":{"type":"string","enum":["last_online","name"],"default":"last_online"}},{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of players.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerList"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players/{player}":{"get":{"tags":["Players"],"summary":"Player profile","description":"Identity, medal counts, crown score, hall-of-fame position and top ranks.","operationId":"getPlayer","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"}],"responses":{"200":{"description":"The player profile.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players/{player}/stats":{"get":{"tags":["Players"],"summary":"Every statistic for one player","operationId":"getPlayerStats","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"},{"name":"ids","in":"query","description":"Comma-separated stat ids to return instead of all of them.","schema":{"type":"string"},"example":"jump,mine_diamond_ore"}],"responses":{"200":{"description":"The player's statistics.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players/{player}/advancements":{"get":{"tags":["Players"],"summary":"Advancement progress for one player","description":"Recipe unlocks are excluded by default because they dominate the raw file.","operationId":"getPlayerAdvancements","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"},{"name":"include","in":"query","description":"Set to 'recipes' to also include recipe unlocks.","schema":{"type":"string","enum":["recipes"]}},{"name":"completed","in":"query","description":"Set to false to also list advancements still in progress.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Advancement progress.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/players/{player}/milestones":{"get":{"tags":["Players"],"summary":"A player's journey through the game","description":"When a player first appeared, the progression beats they have hit and how long each took, the rarest advancement they hold, and anything they were **first on the server** to reach.\n\n`first_seen` is derived from the timestamps on their advancement file. When `first_seen_estimated` is true the player was already here when advancement tracking began, so the date is a floor rather than their real join date.","operationId":"getPlayerMilestones","parameters":[{"name":"player","in":"path","required":true,"description":"A Minecraft UUID (dashed or bare) or an exact in-game name (case-insensitive).","schema":{"type":"string"},"example":"Clavalava"}],"responses":{"200":{"description":"The player's milestones.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/hall-of-fame":{"get":{"tags":["Community"],"summary":"Crown hall of fame","description":"Players ranked by crown score, awarded for 1st, 2nd and 3rd places across all statistics.","operationId":"getHallOfFame","parameters":[{"name":"limit","in":"query","description":"Maximum number of records to return (1–500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"offset","in":"query","description":"Number of records to skip before returning results.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The hall of fame.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/events":{"get":{"tags":["Community"],"summary":"Weekly community events","operationId":"listEvents","parameters":[{"name":"active","in":"query","description":"Filter to currently running or finished events.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The event list.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/events/{event_id}":{"get":{"tags":["Community"],"summary":"One event","operationId":"getEvent","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string"},"example":"explorer_week6"}],"responses":{"200":{"description":"The event.","headers":{"ETag":{"description":"Strong validator; send back as If-None-Match to get a 304.","schema":{"type":"string"}},"Cache-Control":{"description":"How long the response may be cached.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error response (RFC 9457 Problem Details).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Envelope":{"type":"object","description":"Every successful response uses this wrapper.","required":["data","meta"],"properties":{"data":{"description":"The requested resource or array of resources."},"meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","properties":{"data_updated_at":{"type":["string","null"],"format":"date-time","description":"When the underlying statistics were last regenerated from the world save."},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":true},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching records."},"count":{"type":"integer","description":"Records in this page."},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":["string","null"],"format":"uri","description":"Absolute URL of the next page, or null."},"previous":{"type":["string","null"],"format":"uri"}}},"Value":{"type":"object","description":"A statistic value together with its unit and convenience conversions.","properties":{"value":{"type":"number","description":"The raw value, in the stat's native unit."},"unit":{"type":"string","enum":["int","cm","ticks","tenths_of_heart"]},"display":{"type":"string","description":"Human-readable rendering, ready to print."},"converted":{"type":["object","null"],"description":"Unit conversions where they make sense (metres, hours, hearts…).","additionalProperties":{"type":"number"}}}},"Player":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":["string","null"],"description":"Last known in-game name."},"edition":{"type":"string","enum":["java","bedrock"],"description":"Bedrock players join through Geyser."},"ranked":{"type":"boolean","description":"Whether the player has met the minimum playtime and appears in rankings."},"last_online":{"type":["string","null"],"format":"date-time"},"skin":{"type":["string","null"],"description":"Mojang skin texture hash."},"textures":{"type":"object","description":"Ready-made image URLs for skin, head and body renders.","properties":{"skin":{"type":["string","null"],"format":"uri"},"head":{"type":["string","null"],"format":"uri"},"body":{"type":["string","null"],"format":"uri"}}}}},"Stat":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"unit":{"type":"string"},"leaderboard":{"type":"string","format":"uri"},"record":{"type":["object","null"],"description":"Current record holder for this statistic.","allOf":[{"$ref":"#/components/schemas/Value"}]}}},"StatList":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Stat"}}}}]},"Advancement":{"type":"object","properties":{"id":{"type":"string","example":"minecraft:nether/all_effects"},"title":{"type":"string","example":"How Did We Get Here?"},"category":{"type":"string","example":"nether"},"source":{"type":"string","enum":["vanilla","datapack"],"description":"`vanilla` is a real in-game advancement; `datapack` is bookkeeping a datapack files as one."},"completed_by":{"type":"integer","description":"Number of players who hold it."},"rarity":{"type":"number","description":"Fraction of scanned players holding it (0–1)."},"rarity_percent":{"type":"number","description":"The same figure as a percentage."},"icon":{"type":["string","null"],"format":"uri"},"wiki":{"type":"string","format":"uri"}}},"AdvancementList":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Advancement"}}}}]},"PlayerList":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Player"}}}}]},"LeaderboardEntry":{"allOf":[{"$ref":"#/components/schemas/Value"},{"type":"object","properties":{"rank":{"type":"integer","minimum":1},"player":{"$ref":"#/components/schemas/Player"}}}]},"Leaderboard":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"}}}}]},"Health":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"data_updated_at":{"type":["string","null"],"format":"date-time"},"data_age_seconds":{"type":["integer","null"]},"data_stale":{"type":"boolean"},"uptime_seconds":{"type":"integer"}}}}}]},"Problem":{"type":"object","description":"RFC 9457 Problem Details.","properties":{"type":{"type":"string","format":"uri","description":"Stable identifier for the error class."},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"Human-readable explanation of this specific failure."},"instance":{"type":"string","description":"The path that produced the error."}}}}}}