PlayHive API Updates

Today we're launching the first part of our catalogue API, currently in preview. Our end goal is a fully available index of all our released cosmetics.

The catalogue currently splits our costumes into these categories:

STORE_PURCHASE,
QUEST_POINTS,
GAME_LEVEL,
BUNDLE_PURCHASE,
SPECIAL_EVENT,
ACHIEVEMENT,
GAME_PURCHASE,
LEGACY

Depending on the category, additional information is provided:

• Store purchase costumes list the 'parent' store offer, together with the other global unlocks that offer provides, and the Minecraft-store product ID.
• Quest point costumes list the price at the time of release.
• Active game level costumes list the game and the required level.
• Bundle purchase costumes list the store offer if the bundle is still available, or a unique bundleId if not.
• Special event costumes list the event, and the lastAvailable date if available.
• Achievement costumes list the requirement for unlocking the costume (for example, Discord boosting, newsletter subscribing).
• Game purchase costumes list where the costume is/was available to purchase from.
• Legacy costumes, often previous Special Event costumes, list the original type and the metadata from the original type.

Currently two endpoints are available:

https://api.playhive.com/v0/catalogue/costumes?limit=50&offset=0

https://api.playhive.com/v0/catalogue/costumes/id

For this endpoint, we're using more proper REST-practices for defining the limit and offset. Both limit and offset can be omitted for the default 50 limit and 0 offset.

Our starting catalogue contains information from both automated and manual sources, and WILL contain mistakes. We are continuing to build out the internal tooling to improve and maintain this data in a better way.

As this is a preview API, return structures will likely change in the future, and we will NOT be versioning this API yet. We currently advise against production use in actual creations, but it's ready for feedback and experimentation.

When this API leaves preview, all the return types will be fully documented.

If you notice any issues, or have other feedback, email us at api[@]hivemc.com.

We only read/action emails about the api.playhive.com public API, all other emails will be deleted. This is not a generic support email. Depending on volume and priorities, we can't promise that all emails will get a (timely) response.

Using the new /player/search/{partial} endpoint, you can query matching players by 'prefix'.

The prefix must be between 4 and 15 (inclusive) alphanumeric or space characters. The returned array is at most 10 items. Where possible, active players are prioritized in the search results.

As with all API methods, this comes with no (long term) availability assurances.

Try it out and find more on the API documentation page.

APIs for SkyWars: Classic and Kits are now available.

For both, statistics are only available for all-time:

/game/all/sky-classic/{player}

/game/all/sky-kits/{player}

Please note XP is shared between SkyWars: Lucky Ores, Classic and Kits.

The addition of the Kits endpoint does not indicate any plans for the return of this mode to the server.

For supported games, level unlocks are now available using the game meta endpoint. For an example, check out the BedWars Game Meta endpoint.

The endpoint has been updated to include two arrays:

levelUnlocks contains an ordered array, level to unlock array, containing both game-specific and global unlocks for each level. For game-specific unlocks, this looks like:

{
  "name": "Creeper",
  "icon": "https://cdn.playhive.com/icons/locker/sky/flag/creeper.png",
  "type": "Player Flag",
  "global": false
}

Please note icon MAY be null. Global is false for all game-specific unlocks.

For global unlocks, global is true, and an additional field globalCosmetic provides the entire meta for the global unlock, such as:

{
  "name": "Boom boom boom",
  "icon": "https://cdn.playhive.com/avatars/sky-boom-boom-boom.png",
  "type": "Avatar",
  "global": true,
  "globalCosmetic": {
    "url": "https://cdn.playhive.com/avatars/sky-boom-boom-boom.png",
    "name": "Boom boom boom",
    "type": "avatar"
  }
}

Please note icon MAY be null.

The other new array, levelUnlockTypes, contains the game-specific types you will encounter in the levelUnlocks array. It provides the default unlock, or null if there is no default. It also provides the category icon.

As this update only provides new data, this is not behind a version/feature flag. Hub title meta is always the expanded meta, but unresolved as the display is not specific to a player.

SkyWars Classic shares XP (level progression) with SkyWars, but has separate statistics for games played, victories, kills, et cetera. These will be available on the API in the near future.

Details on the main updates site.

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.