Hive Games API Guide

Introduction

This document provides a comprehensive guide to the Hive Games API, focusing on endpoints relevant for retrieving player statistics and game data. This guide is intended for developers building applications that integrate with the Hive platform, such as player statistics websites. The API offers various endpoints to access player information, game-specific statistics, leaderboards, and other catalogue data.

General API Information

Base URL: https://api.playhive.com/v0/

Authentication: As of July 1st, 2025, an API key will be mandatory for production use-cases. Without a valid API key, rate limits will be severely lowered. To obtain an API key, contact api@hivemc.com [1]. Authentication details, such as how to include the API key in requests (e.g., via headers), are not explicitly detailed in the public documentation but are generally handled through Authorization headers (e.g., Bearer <token>) or custom headers [2] [3].

Rate Limiting: Automated rate limiting is applied to prevent abuse. If the limit is exceeded, appropriate rate-limiting headers will be returned in the response. It is crucial to handle these responses gracefully to avoid being blocked [1].

Supported Games: The Hive API supports data for the following games: wars, dr, hide, sg, murder, sky, ctf, drop, ground, build, party, bridge, grav, bed.

API Endpoints

Below is a detailed breakdown of the available API endpoints, their functionalities, parameters, and expected responses.

1. Player Search

Endpoint: /player/search/{partial} Method: GET Summary: Searches for players whose usernames start with the provided partial string.

Parameter	Type	Description	Constraints
partial	string	Partial username to search for	4-15 characters

Example Response (200 OK):

[
  {
    "UUID": "<player-uuid>",
    "username": "<player-username>",
    "username_cc": "<player-username-with-color-codes>"
  }
]

Error Response (422 Unprocessable Entity): Input validation failed.

2. Player Game Statistics

2.1 Get All Game Statistics for a Player

Endpoint: /game/all/all/{identifier} Method: GET Summary: Retrieves all game statistics for a given player across all games.

Parameter	Type	Description
identifier	string	Player UUID or username

Example Response (200 OK):

{
  "<game-name-1>": { /* game specific stats */ },
  "<game-name-2>": { /* game specific stats */ }
}

Error Response (404 Not Found): Player not found.

2.2 Get Main Game Statistics for a Player

Endpoint: /game/all/main/{identifier} Method: GET Summary: Retrieves main game statistics for a given player.

Parameter	Type	Description
identifier	string	Player UUID or username

Example Response (200 OK):

{
  "main": { /* main game specific stats */ }
}

Error Response (404 Not Found): Player not found.

2.3 Show Player All-Time Statistics for a Specific Game

Endpoint: /game/all/{game}/{player} Method: GET Summary: Retrieves all-time statistics for a specific game and player.

Parameter	Type	Description
game	string	Game name (e.g., wars, bed)
player	string	Player UUID or username

Example Response (200 OK):

{
  "<stat-name-1>": "<value>",
  "<stat-name-2>": "<value>"
}

Error Response (404 Not Found): Game does not exist or does not have leaderboards.

3. Leaderboards

3.1 Show All-Time Leaderboard for a Game

Endpoint: /game/all/{game} Method: GET Summary: Retrieves the all-time leaderboard for a specific game.

Parameter	Type	Description
game	string	Game name (e.g., wars, bed)

Example Response (200 OK):

[
  { "UUID": "<player-uuid>", "username": "<player-username>", "value": <score> },
  // ... more entries
]

Error Response (404 Not Found): Game does not exist or does not have leaderboards.

3.2 Show Current Monthly Leaderboard for a Game

Endpoint: /game/monthly/{game} Method: GET Summary: Retrieves the current monthly leaderboard for a specific game.

Parameter	Type	Description
game	string	Game name (e.g., wars, bed)

Example Response (200 OK):

[
  { "UUID": "<player-uuid>", "username": "<player-username>", "value": <score> },
  // ... more entries
]

Error Response (404 Not Found): Game does not exist or does not have monthly leaderboards.

3.3 Show Specific Monthly Leaderboard for a Game

Endpoint: /game/monthly/{game}/{year}/{month}/{amount}/{skip} Method: GET Summary: Retrieves a specific monthly leaderboard for a game with pagination.

Parameter	Type	Description	Default	Max	Min
game	string	Game name
year	integer	Year
month	integer	Month (1-12)		12	1
amount	integer	Number of entries to return	50	100	0
skip	integer	Number of entries to skip	0		0

Example Response (200 OK):

[
  { "UUID": "<player-uuid>", "username": "<player-username>", "value": <score> },
  // ... more entries
]

Error Response (404 Not Found): Game does not exist or does not have monthly leaderboards.

3.4 Show Single Player Entry in Current Monthly Leaderboard

Endpoint: /game/monthly/player/{game}/{player} Method: GET Summary: Retrieves a single player's entry in the current monthly leaderboard for a game.

Parameter	Type	Description
game	string	Game name
player	string	Player UUID or username

Example Response (200 OK):

{
  "UUID": "<player-uuid>",
  "username": "<player-username>",
  "value": <score>
}

Error Response (404 Not Found): Game or player does not exist or game does not have monthly leaderboards.

3.5 Show Single Player Entry in Specific Monthly Leaderboard

Endpoint: /game/monthly/player/{game}/{player}/{year}/{month} Method: GET Summary: Retrieves a single player's entry in a specific monthly leaderboard for a game.

Parameter	Type	Description
game	string	Game name
player	string	Player UUID or username
year	integer	Year
month	integer	Month (1-12)

Example Response (200 OK):

{
  "UUID": "<player-uuid>",
  "username": "<player-username>",
  "value": <score>
}

Error Response (404 Not Found): Game or player does not exist or game does not have monthly leaderboards.

4. Global Statistics

Endpoint: /global/statistics Method: GET Summary: Retrieves unique player counts for the entire server and supported games.

Example Response (200 OK):

{
  "unique_players": {
    "global": <total-unique-players>,
    "<game-name-1>": <unique-players-in-game-1>,
    "<game-name-2>": <unique-players-in-game-2>
  }
}

5. Player Activity (Preview)

Endpoint: /player/activity/{uuid} Method: GET Summary: Retrieves recent player activity (up to 10 entries) for a given UUID.

Parameter	Type	Description
uuid	string	Player UUID

Notes:

• Returns a maximum of 10 activity entries. Supported activities include ROUND_PLAYED and LOCKER item unlocked.
• Requires the player to be online or recently online. An anti-sniping delay applies, meaning activities will not update until the player has finished their session.
• Supports Etag for caching: send the latest Etag value in the If-None-Match header to utilize caching and reduce rate limit impact [4].

Example Response (200 OK - ROUND_PLAYED):

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

Example Response (200 OK - LOCKER):

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

6. Game Metadata

Endpoint: /game/meta/{game} Method: GET Summary: Retrieves metadata for a specific game, including level unlocks.

Parameter	Type	Description
game	string	Game name (e.g., wars, bed)

Example Response (200 OK):

{
  "levels": { /* level unlock data */ },
  "achievements": { /* achievement data */ }
}

Error Response (404 Not Found): Game does not exist.

7. Game Maps

Endpoint: /game/map/{game} Method: GET Summary: Lists available maps for a specific game.

Parameter	Type	Description
game	string	Game name (e.g., wars, bed)

Example Response (200 OK):

[
  "<map-name-1>",
  "<map-name-2>"
]

Error Response (404 Not Found): Game does not exist or game has a static map.

8. Catalogue API (Preview)

8.1 List Hub Titles

Endpoint: /catalogue/titles Method: GET Summary: Lists available hub titles.

Notes: Roughly 100 hub titles are currently not available through this API. Some are unused/internal, and others have pending manual validation or misdocumented metadata [4].

8.2 Get Specific Hub Title by ID

Endpoint: /catalogue/titles/{id} Method: GET Summary: Retrieves details for a specific hub title by its ID.

Parameter	Type	Description
id	string	UUID of the hub title

9. Costume Catalogue

Endpoint: /catalogue/costumes Method: GET Summary: Lists available costumes with pagination.

Parameter	Type	Description	Default	Max	Min
amount	integer	Amount of costumes to return	50
skip	integer	Number of costumes to skip	0

Example Response (200 OK):

[
  { "id": "<costume-uuid>", "name": "<costume-name>", "rarity": "<rarity>" },
  // ... more entries
]

Endpoint: /catalogue/costumes/{id} Method: GET Summary: Retrieves details for a specific costume by its ID.

Parameter	Type	Description
id	string	UUID of the costume

Example Response (200 OK):

{
  "id": "<costume-uuid>",
  "name": "<costume-name>",
  "rarity": "<rarity>",
  "description": "<description>"
}

Error Response (404 Not Found): Costume not found.

References

[1] The Hive - API Information. (n.d.). Retrieved from https://support.playhive.com/api/ [2] Authentication - Hive. (n.d.). Retrieved from https://www.mintlify.com/paralect/hive/guides/authentication [3] The Hive Python API Docs. (n.d.). Retrieved from https://dlthub.com/context/source/the-hive [4] PlayHive API Updates. (n.d.). Retrieved from https://api-updates.playhive.com/