HiveAPI

KO | EN

gitlite — search

#javascript #python #typescript #llm #golang #machine-learning #docker #macos #java #cli #kubernetes #vue #security #ios

(★ 34)

TheHive API Documentation

HiveAPI Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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.

**Example Response (200 OK):**
```json
[
  {
    "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.

**Example Response (200 OK):**
```json
{
  "<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.

**Example Response (200 OK):**
```json
{
  "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.

**Example Response (200 OK):**
```json
{
  "<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.

**Example Response (200 OK):**
```json
[
  { "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.

#### 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     |

#### 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.

**Example Response (200 OK):**
```json
{
  "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.

### 4. Global Statistics

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

**Example Response (200 OK):**
```json
{
  "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.

**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):**
```json
[
  {
    "time": 1731372040,
    "type": "ROUND_PLAYED",
    "game": "dr",
    "victory": false
  }
]
```
**Example Response (200 OK - LOCKER):**
```json
[
  {
    "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.

**Example Response (200 OK):**
```json
{
  "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.

**Example Response (200 OK):**
```json
[
  "<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):**
```json
[
  { "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):**
```json
{
  "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/](https://support.playhive.com/api/)
[2] Authentication - Hive. (n.d.). Retrieved from [https://www.mintlify.com/paralect/hive/guides/authentication](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](https://dlthub.com/context/source/the-hive)
[4] PlayHive API Updates. (n.d.). Retrieved from [https://api-updates.playhive.com/](https://api-updates.playhive.com/)

HiveAPI

HiveAPI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

HiveAPI

HiveAPI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README