PlayHive API Updates

Technical updates for the PlayHive REST API

PlayHive API Updates

API Preview: Player Activity API

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.

API Preview: Catalogue API (Hub Titles)

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)

API Preview: Catalogue API (Costumes)

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.

Player partial search endpoint

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.

SkyWars: Classic and Kits API endpoints

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.

Level Unlocks now available on the Game Meta API

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 API

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.

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to PlayHive API Updates.

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.