Documentation menu

API Reference

Players

Player profile, currencies, data store, statistics

GET /api/plugin/players

Search or browse players

Lists players in this network (offline included), most-recently-seen first. Pass ?username= for an exact case-insensitive match, ?search= for a substring match, or neither to page through everyone.

Parameters

  • limit integer query

    Page size.

  • page integer query

    0-based page index.

  • search string query

    Substring match on username.

  • username string query

    Exact, case-insensitive username match.

Responses

  • 200 A page of lightweight player rows (no currencies/namespaces).
200 response 
{
  "items": [
    {
      "uuid": "string",
      "username": "string",
      "gameType": "string",
      "firstSeen": 0,
      "lastSeen": 0,
      "online": false,
      "connection": {
        "serverId": "string",
        "serverType": "string",
        "worldId": "string"
      }
    }
  ],
  "page": 0,
  "limit": 0,
  "total": 0
}

Request

~
curl -X GET http://localhost:8090/api/plugin/players?limit=0&page=0&search=value&username=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
// Exact (case-insensitive) name, most-recently-seen first:
hive.player().findByUsername("Notch").thenAccept(matches -> { });

// Or browse/search the whole network (offline included), 0-based page:
hive.player().listPlayers("not", 0, 50).thenAccept(page -> {
  page.items(); page.total();
});
GET /api/plugin/players/{uuid}

Get a player's profile (online or offline)

Read-only lookup by UUID, valid whether the player is online or offline. Unlike /load it never creates a row. Includes online status and, when online, the current connection (server/world).

Parameters

  • uuid string path required

    Player UUID.

  • gameMode string query

    Scope for the returned stats/namespaces.

Responses

  • 200 The player's profile plus online status.
  • 404 No player with this UUID has ever been seen on the network.
200 response 
{
  "uuid": "string",
  "username": "string",
  "gameType": "string",
  "firstSeen": 0,
  "lastSeen": 0,
  "online": false,
  "connection": {
    "serverId": "string",
    "serverType": "string",
    "worldId": "string"
  },
  "currencies": [
    {
      "currencyName": "string",
      "balance": 0
    }
  ],
  "namespaces": [
    {
      "namespace": "string",
      "data": "string",
      "version": 0
    }
  ]
}

Request

~
curl -X GET http://localhost:8090/api/plugin/players/{uuid}?gameMode=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
// Read-only lookup, online or offline. Never creates a row.
hive.player().fetchProfile(uuid, "global").thenAccept(maybe -> {
  if (maybe.isEmpty()) return;           // 404: never seen
  PlayerProfile p = maybe.get();
  if (p.online()) {
    PlayerConnection at = p.connection(); // serverId / worldId
  }
});
POST /api/plugin/players/{uuid}/load

Load (and upsert) a player on join

Creates the player row the first time this network sees the UUID, then returns the full profile: identity, currencies, per-game namespaces and first/last seen. Call this when a player joins one of your servers.

Parameters

  • uuid string path required

    Player UUID.

  • gameMode string query

    Scope for stats/namespaces. Defaults to "global".

  • gameType string query

    Origin engine (MINECRAFT/HYTALE); recorded once, on first sight.

  • username string query

    Current username; refreshed on every load.

Responses

  • 200 The player's durable profile (freshly upserted).
200 response 
{
  "uuid": "string",
  "username": "string",
  "gameType": "string",
  "firstSeen": 0,
  "lastSeen": 0,
  "currencies": [
    {
      "currencyName": "string",
      "balance": 0
    }
  ],
  "namespaces": [
    {
      "namespace": "string",
      "data": "string",
      "version": 0
    }
  ]
}

Request

~
curl -X POST http://localhost:8090/api/plugin/players/{uuid}/load?gameMode=value&gameType=value&username=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
// On join: upserts the player row and returns their profile.
hive.player()
    .fetchPlayerData(uuid, username, "skywars", GameType.HYTALE)
    .thenAccept(data -> {
      data.getCurrencies();              // network-wide balances
      data.getNamespace("skywars");      // this game's private JSON
    });
GET /api/plugin/players/{uuid}/statistics

Read a player's statistics

Returns the player's statistic values for the given game mode, one entry per (name, period). Periods are DAILY, WEEKLY, MONTHLY and LIFETIME.

Parameters

  • uuid string path required

    Player UUID.

  • gameMode string query

    Game-mode scope. Defaults to "global".

Responses

  • 200 The player's statistics for the requested game mode.
200 response 
{
  "playerUuid": "string",
  "gameMode": "string",
  "statistics": [
    {
      "statisticName": "string",
      "gameMode": "string",
      "periodType": "string",
      "periodStart": "string",
      "value": 0,
      "updatedAt": 0
    }
  ]
}

Request

~
curl -X GET http://localhost:8090/api/plugin/players/{uuid}/statistics?gameMode=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.player().getStatistics(uuid, "skywars").thenAccept(stats -> {
  StatisticValue weekly = stats.getStatistic("wins", PeriodType.WEEKLY);
  long wins = weekly != null ? weekly.getValue() : 0;
});
POST /api/plugin/players/{uuid}/statistics/increment

Increment a statistic

Adds to a named statistic and returns its new value in every period at once (DAILY/WEEKLY/MONTHLY/LIFETIME). This is the counter-and-leaderboard primitive.

Parameters

  • uuid string path required

    Player UUID.

Request body

application/json 
{
  "name": "string",
  "gameMode": "string",
  "amount": 0
}

Responses

  • 200 The updated per-period values for the statistic.
  • 400 Bad Request
200 response 
{
  "statisticName": "string",
  "gameMode": "string",
  "newValues": {}
}

Request

~
curl -X POST http://localhost:8090/api/plugin/players/{uuid}/statistics/increment \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","gameMode":"string","amount":0}'
// Bumps every period at once; returns the new per-period values.
hive.player().incrementStatistic(uuid, "wins", "skywars", 1)
    .thenAccept(newValues -> {
      // { DAILY=3, WEEKLY=11, MONTHLY=40, LIFETIME=512 }
      long lifetime = newValues.get("LIFETIME");
    });