PlayHive API Updates

We are replacing the leaderboard source for certain API and in-game /leaderboard queries, to improve performance and resolve frequent leaderboard outages.

The modern source will become the default in the future, but you can opt-in now.

Noticeable changes and side effects:

• Previously, the position of an individual player was calculated by getting the sum of players that had a score higher than that player, meaning multiple players could have the same position. Now, players with the same score are sorted in reverse lexicographical order. If this affects your use case, or you think this might have any consequences, you can let us know at api[@]hivemc.com.
• For individual player leaderboard requests, uncached requests might be a few ms slower for players near the top of the leaderboard, but many (up to ~50) ms quicker for those lower down. Cached requests are unaffected when it comes to speed.

To opt-in, set the X-Hive-Leaderboard-Source header to 'modern'. Not sending this header, or to an invalid value, will default to 'legacy'. The used source will be reflected in the response header of the same name.

Caching is dependent on the header, that is, the cache will not be 'poisoned' by requests to the same endpoint with different headers.

We're releasing a new API in preview today: player activity.

The player activity API returns an array of at most 10 activity entries for the given UUID. Supported activities are currently game (round) played and locker item unlocked.

An empty array will be returned if no recent activities exist, or for sessions in which the player had the Appear Offline toggle enabled. Players can currently opt out of this API by appearing offline permanently - an additional toggle will be added soon. Activities will NOT update until the player has finished their session (logged out): this is an anti-sniping measure, and we're looking into ways to either opt-in to public live updates, or other solutions such as delays.

This is our first endpoint that properly supports Etag: if your request matches our cache, 304 Not Modified is returned, and you won't impact your main rate limit. Simply send the latest Etag value in the If-None-Match header to utilize this.

https://api.playhive.com/v0/player/activity/UUID

ROUND_PLAYED example:

{
  "time": 1731372040,
  "type": "ROUND_PLAYED",
  "game": "dr",
  "victory": false
}

LOCKER example:

{
  "time": 1731368673,
  "type": "LOCKER",
  "unlock_type": "avatar",
  "unlock_id": "744742ac-bf38-4f43-b292-702d347ec497"
}

Unlock IDs are compatible with existing catalogue APIs, and for unimplemented catalogue endpoints, will be compatible once those release.

We'll be implementing additional activities, and expanding the information in the current ones. For suggestions and 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.

Following up from the Costume Catalogue API, we're launching the Hub Titles Catalogue API in preview today.

The response format is generally identical to costumes. For general information about the correctness, availability and other notes about the preview catalogue APIs, make sure to read the Costume API post. For hub titles specifically:

• Roughly 100 hub titles are currently not available through this API. Whilst a bulk of these are unused/internal titles, there are a good number of in-use titles not available.
• Especially achievement and special event titles are pending manual validation, and a number of titles will have misdocumented metadata.

https://api.playhive.com/v0/catalogue/titles

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

The following parameters are now available for all catalogue APIs:

• type, optional, can be STORE_PURCHASE, QUEST_POINTS, GAME_LEVEL, BUNDLE_PURCHASE, SPECIAL_EVENT, ACHIEVEMENT, GAME_PURCHASE or LEGACY
• active, optional, can be true, false, 1 or 0
• originalUnlockType, optional, same as type except for LEGACY
• game, optional, can be any lowercase shortname (dr, hide, et cetera)

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.