Klyx API

Hello! and welcome to the Klyx API. Last updated 14th October 2026.

This is a public, read-only JSON for Klyx events and players. Every URL below is relative to https://klyx.org.

Everything comes from the same data as the site. This means that the API never disagrees with what you see on an event or player page. If you do notice something that doesn't match, please let us know!

Things to know

  • Hidden events. While an event's results are hidden (e.g. game 8), every endpoint hides them too: coins come back as 0, ranks as null, and the in-progress game's scores are empty.
  • Coins before multipliers. Some games are worth more than others. Coin totals and ranks are before those multipliers, the same as the standings on an event page. Fields ending in WithMultipliers are the totals after.
  • Names or UUIDs. Anywhere that takes a player, you can give a Minecraft username (any capitalisation) or their UUID. A name goes to whoever used it most recently in a Klyx event. UUIDs never change, so use those if you're storing links.
  • Errors come back as JSON with a reason, e.g. { "reason": "not_found" }, and a matching status: 400 for a bad request, 404 for something that doesn't exist, 500 if something broke on our end.

Player profile

GET /api/player/:nameOrUUID

A player's career across every Klyx event they've played.

curl https://klyx.org/api/player/Asleepp

{
    "profile": {
        "uuid": "5c0b4deb-a01a-48bb-b9b1-0a99762b2bc1",
        "username": "Asleepp",
        "aliases": ["Asleepp"],
        "eventsAttended": 3,
        "careerCoins": 6716,
        "averageCoins": 2239,
        "careerCoinsWithMultipliers": 10869,
        "averageCoinsWithMultipliers": 3623,
        "bestFinish": 6,
        "history": [
            {
                "eventId": "kgbirthdaybrawl2",
                "eventName": "Klyx Games: Birthday Brawl 2",
                "startDate": "2026-09-06T19:00:00.000Z",
                "username": "Asleepp",
                "teamName": "Elite Four",
                "teamColor": "rgb(85, 255, 85)",
                "coinsEarned": 2246,
                "coinsEarnedWithMultipliers": 3467,
                "rank": 21,
                "eventHidden": false
            }
        ]
    }
}
  • Trimmed above to one history entry, and without topTeammates.
  • username is their latest name. aliases is every name they've played under, newest first.
  • topTeammates is up to 3 players they've shared a team with most, and how many events.
  • history is newest first. rank is their place among every player in that event.

Errors: 404 { "profile": null, "reason": "not_found" } if nobody by that name or UUID has played.

Head-to-head

GET /api/player/:a/vs/:b

How two players did in every event they both played.

curl https://klyx.org/api/player/Asleepp/vs/BitSquidd

{
    "message": "Asleepp and BitSquidd have played 1 klyx together",
    "a": { "uuid": "5c0b4deb-a01a-48bb-b9b1-0a99762b2bc1", "username": "Asleepp" },
    "b": { "uuid": "7f548cc3-70b3-458e-91ad-66c11867f5e9", "username": "BitSquidd" },
    "shared": 1,
    "aWins": 1,
    "bWins": 0,
    "ties": 0,
    "events": [
        {
            "eventId": "kgonyx",
            "eventName": "Klyx Games: Onyx 2",
            "startDate": "2026-03-29T18:00:00.000Z",
            "aRank": 11,
            "bRank": 13,
            "winner": "a"
        }
    ]
}
  • message is ready to show as is. With nothing in common it reads <a> and <b> have never shared a klyx!, using their proper names.
  • winner is whoever finished higher: "a", "b", or null for a tie.
  • Hidden events, should they ever exist, aren't counted since there are no ranks to compare yet.

Errors: 404 with missing set to "a" or "b" and a message, e.g. { "reason": "not_found", "missing": "b", "message": "diaduckk hasn't played a klyx yet!" }.

Leaderboard

GET /api/players

The top 50 players of all time.

curl https://klyx.org/api/players
curl "https://klyx.org/api/players?sort=average"

?sort=average, trimmed to the top player:

{
    "sort": "average",
    "players": [
        {
            "uuid": "9221a795-070c-482c-8de2-834eff881268",
            "username": "CreepyBrawler",
            "eventsAttended": 4,
            "careerCoins": 13457,
            "careerCoinsWithMultipliers": 21265,
            "averageCoins": 3364,
            "averageCoinsWithMultipliers": 5316,
            "bestFinish": 1
        }
    ]
}
  • sort=career (the default) ranks by total coins.
  • sort=average ranks by average coins per event, among players with at least 3 events, so playing lots doesn't automatically make you top.

Errors: 400 { "players": null, "reason": "bad_sort" } for any other sort.

Events

GET /api/events

Every event, newest first. Use an id from here with the event endpoint below.

curl https://klyx.org/api/events

{
    "events": [
        {
            "id": "kgpoh",
            "name": "Klyx Games: Pixels Of Hope",
            "startDate": "2026-10-10T19:00:00.000Z",
            "hidden": false
        },
        {
            "id": "kgyappertron",
            "name": "Klyx Games: Yappertron",
            "startDate": "2026-09-12T19:00:00.000Z",
            "hidden": false
        }
    ]
}
  • Trimmed above to the two newest.
  • An id is also the last part of an event page's address: kgonyx from klyx.org/event/kgonyx.
  • hidden is true while an event's results are hidden. It's still listed, but the event endpoint hides its scores.
  • An event with no date yet has startDate: null and comes last.

Errors: only 500 if something broke on our end.

Event

GET /api/event/:eventId

One event's teams, players and per-game scores. This is what the live standings on an event page poll.

curl https://klyx.org/api/event/kg8

{
    "event": {
        "_id": "kg8",
        "eventName": "Klyx Games #8",
        "startDate": "2026-06-28T14:00:00.000Z",
        "hidden": false,
        "teams": [
            {
                "id": "pink",
                "teamName": "Pink Penguins",
                "color": 16733695,
                "coins": 16387,
                "players": [
                    { "id": "d4e38500-2701-4d1b-b820-4eb69fac44da", "username": "Trolliant", "indivCoins": 4163 }
                ]
            }
        ],
        "games": [
            {
                "id": "souls",
                "gameName": "Souls",
                "multiplier": 1,
                "hidden": false,
                "gameScore": { "d4e38500-2701-4d1b-b820-4eb69fac44da": 166 },
                "totalCoins": { "pink": 751 }
            }
        ]
    }
}
  • Trimmed above to one team, one player and one game.
  • This is the raw event, so its numbers are after multipliers: indivCoins, coins, gameScore and totalCoins. Divide a gameScore by its game's multiplier to get the before number.
  • gameScore is keyed by player UUID, totalCoins by team id.
  • color is an RGB integer: 16733695 is #ff55ff.
  • Responses carry an ETag. Send it back as If-None-Match and you'll get an empty 304 when nothing has changed.

Errors: 404 { "event": null, "reason": "not_found" }.