PlayHive API Updates

Parkour Worlds data is available under the all-time PARKOUR endpoint:

v0/game/all/parkour/username

The 'parkours' array exists for players that have played at least one course in any world. The structure is world name -> course name -> data.

Worlds will only exist if the player has played at least one course in that world. Once a player has played one course, all courses will be initialized: the 'best_run_time' can be null if a player has never played or finished the individual course. The arrays can be empty.

Note that 'best_checkpoint_times' is updated outside of the context of a run: that is, the times can be from different runs. 'best_run_time' is the best overall run, so not equal to the combined values of 'best_checkpoint_times'.

All (run) times are stored in server ticks. Hive runs at 20TPS, so one tick is 50MS.

Star counts are provided at course, world and global level.

We fixed an issue where the maps endpoints was returning stale (outdated) information.

The returned amount of entries for all-time leaderboards is now 100, to match in-game.

Added 'teleporters_used', 'launchpads_used' and 'flares_used' to Survival Games. These fields will fill correctly for single-user requests, but will return 0 when part of a leaderboard lookup, until that player has played at least one game since this change.

The hat a player has equipped is now listed as equipped_hat on the 'main' endpoint.

Meta-reference hub titles now correctly resolve when hub titles are returned as a map.

For multi-key stat-track hub titles, where the operation is divide, the style is now declared. For now, this is one of: percent or dot. Additionally, hub titles with the percent style now resolve correctly like this, as they do in-game.

Meta-reference hub titles (hub titles that use a player-specific, but immutable piece of data) are now resolved correctly by the API. As these titles are static per-player, they show up as normal titles on the API (and are always fully resolved).

As we work towards a unified codebase, the code expanding dynamic hub titles differs between the API and in-game. Because of this, at times there might be a difference in display values: we do consider these bugs, and will fix them as they are discovered.

Leaderboards for seasons are now available. They are very similar to monthly ones, both whole leaderboard and specific entry endpoints are available. As seasons run longer than monthly leaderboards, you can request more data than monthly ones: up to 1000 in (at most) 100 increments.

In the future, as more seasons are released, we will add an endpoint to get the season information for games: for now, only 'bed' season '1' exists.

The previously announced changes to hub titles are now available, by opting in using the specified headers.

As we keep expanding hub titles, the header to fully resolve hub titles has been formally renamed to:

X-Hive-Resolve-Dynamic-Hub-Titles

That said, the previously announced X-Hive-Resolve-Stat-Track functions identically.

Before Treasure Wars rewards are given out, we are removing a small set of players that are ineligible for rewards given their account status.

This will lead to a small adjustment of the final position of players, and in some cases, place them in a different (better) tier.

We currently only provide the basic v0 API versioning, which doesn't allow for much flexibility when we want or need to break existing response formats.

As part of an upcoming feature, we have to modify the hub_title_unlockedresponse format from a String array to an array of objects, so we can provide additional meta data.

To support this without breaking existing implementations, we'll be using a GitHub-style API versioning header: X-Hive-Api-Version. If you don't send this header (or use an unsupported value), you'll only see new fields, but not fields that we've modified since. For the changes to hub_title_unlocked, either set this header to 2024-03-29 or latest. We don't recommend latest for production use cases, as you'll opt in to future changes as well.

We'll start maintaining a list of API versions, and associated changes, on this website in the future.

Starting on March 29th, if you're opted in you'll see hub titles with the special_type set to stat_track, which are dynamic hub titles that change depending on a users statistics. A simple stat_track looks like this:

{
    "display": "(Number) SkyWars Wins",
    "special_type": "stat_track",
    "stat_track": [
        {
            "game": "sky",
            "key": "victories",
            "placeholder": "(Number)"
        }
    ]
}

A complex one looks like:

{
    "display": "(Number) SkyWars Winrate",
    "special_type": "stat_track",
    "stat_track": [
        {
            "game": "sky",
            "keys": [
                "victories",
                "played"
            ],
            "operation": "divide",
            "placeholder": "(Number)"
        }
    ]
}

Operation is: divide, add, or subtract.

These are examples and not real hub titles.

By default, display will show the placeholder where the real number goes. You can opt-in to have the API show the actual hub title by setting the X-Hive-Resolve-Stat-Track header to true. This works both with and without the Version header.