Documentation menu

API Reference

Punishments

Bans, mutes, warns, kicks + IP punishments

POST /api/plugin/punishments/create

Issue a punishment by UUID

Bans, mutes, warns or kicks a player by UUID. durationMs null is permanent; ipBased also covers the player's last-known IP.

Request body

application/json 
{
  "playerUuid": "string",
  "playerName": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "ipBased": false,
  "issuerUuid": "string",
  "issuerName": "string"
}

Responses

  • 200 OK.
  • 400 Bad Request
200 response 
{
  "id": 0,
  "playerUuid": "string",
  "playerName": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "expiresAt": 0,
  "ipBased": false,
  "active": false,
  "ipAddress": "string",
  "issuerUuid": "string",
  "issuerName": "string",
  "issuedAt": 0
}

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/create \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerUuid":"string","playerName":"string","type":"string","reason":"string","durationMs":0,"ipBased":false,"issuerUuid":"string","issuerName":"string"}'
// Ban by UUID. durationMs = null is permanent; ipBased also bans the IP.
hive.punishments().createPunishment(
    targetUuid, targetName, PunishmentType.BAN, "Cheating",
    null, false, issuerUuid, issuerName)
  .thenAccept(p -> { /* p.getId(), p.isActive() */ });
POST /api/plugin/punishments/create-by-name

Issue a punishment by username

Same as create, keyed by username for when the target is offline and no UUID is at hand.

Request body

application/json 
{
  "playerName": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "ipBased": false,
  "issuerUuid": "string",
  "issuerName": "string"
}

Responses

  • 200 OK.
  • 400 Bad Request
200 response 
{
  "id": 0,
  "playerUuid": "string",
  "playerName": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "expiresAt": 0,
  "ipBased": false,
  "active": false,
  "ipAddress": "string",
  "issuerUuid": "string",
  "issuerName": "string",
  "issuedAt": 0
}

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/create-by-name \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerName":"string","type":"string","reason":"string","durationMs":0,"ipBased":false,"issuerUuid":"string","issuerName":"string"}'
// Issue against a name when the target isn't online to resolve a UUID.
hive.punishments().createPunishmentByName(
    "Griefer", PunishmentType.MUTE, "Spam",
    3_600_000L /* 1h */, false, issuerUuid, issuerName);
POST /api/plugin/punishments/create-ip

Issue an IP-only punishment

Punishes an IP with no associated player (ban-evasion ranges). A null/blank IP is a graceful no-op (204).

Request body

application/json 
{
  "ipAddress": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "issuerUuid": "string",
  "issuerName": "string"
}

Responses

  • 200 Created. Returns 204 when the IP was blank (no-op).
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/create-ip \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ipAddress":"string","type":"string","reason":"string","durationMs":0,"issuerUuid":"string","issuerName":"string"}'
// Ban an IP with no associated player (e.g. ban-evasion ranges).
hive.punishments().createIpOnlyPunishment(
    "203.0.113.7", PunishmentType.BAN, "Ban evasion",
    null, issuerUuid, issuerName);
POST /api/plugin/punishments/ip

Record a player's current IP

Stores a player's current IP so IP-based punishments can match them. No body returned.

Request body

application/json 
{
  "playerUuid": "string",
  "playerName": "string",
  "ipAddress": "string"
}

Responses

  • 204 IP recorded.
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/ip \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerUuid":"string","playerName":"string","ipAddress":"string"}'
// Record a player's current IP so IP-based bans can match them.
hive.punishments().updatePlayerIp(playerUuid, playerName, "203.0.113.7");
GET /api/plugin/punishments/player-name/{name}

List a player's punishments by name

Returns punishments for a username. activeOnly=true (default) filters to currently-effective ones.

Parameters

  • name string path required

    Username.

  • activeOnly boolean query

Responses

  • 200 OK.
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/punishments/player-name/{name}?activeOnly=0 \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.punishments().queryByName("Griefer", true /* activeOnly */)
    .thenAccept(list -> { });
GET /api/plugin/punishments/player-name/{name}/history

Punishment history by name

All punishments for a username including expired/revoked, newest first, paginated.

Parameters

  • name string path required

    Username.

  • limit integer query
  • offset integer query

Responses

  • 200 OK.
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/punishments/player-name/{name}/history?limit=0&offset=0 \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.punishments().historyByName("Griefer", 25 /* limit */, 0 /* offset */)
    .thenAccept(history -> { });
GET /api/plugin/punishments/player/{uuid}

List a player's punishments by UUID

Returns punishments for a UUID. activeOnly=true (default) filters to currently-effective ones.

Parameters

  • uuid string path required

    Player UUID.

  • activeOnly boolean query

Responses

  • 200 OK.
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/punishments/player/{uuid}?activeOnly=0 \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.punishments().queryForPlayer(playerUuid, true /* activeOnly */)
    .thenAccept(list -> { /* active punishments */ });
GET /api/plugin/punishments/player/{uuid}/history

A player's full punishment history

All punishments for a UUID including expired/revoked, newest first, paginated.

Parameters

  • uuid string path required

    Player UUID.

  • limit integer query
  • offset integer query

Responses

  • 200 OK.
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/punishments/player/{uuid}/history?limit=0&offset=0 \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.punishments().queryForPlayer(playerUuid, false /* include expired */)
    .thenAccept(history -> { });
GET /api/plugin/punishments/query

Query punishments by player and/or IP

Matches on playerUuid and/or ip (alt-account sweeps). activeOnly defaults to true.

Parameters

  • activeOnly boolean query
  • ip string query
  • playerUuid string query

    Optional player UUID filter.

Responses

  • 200 OK.
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/punishments/query?activeOnly=0&ip=value&playerUuid=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
// Match by player and/or last-known IP (alt-account sweeps).
hive.punishments().queryForPlayerAndIp(playerUuid, "203.0.113.7", true)
    .thenAccept(list -> { });
POST /api/plugin/punishments/remove

Revoke a punishment by id

Lifts a single punishment. The actor is recorded as who revoked it.

Request body

application/json 
{
  "punishmentId": 0,
  "actorUuid": "string",
  "actorName": "string",
  "reason": "string"
}

Responses

  • 200 OK.
  • 400 Bad Request
200 response 
{
  "id": 0,
  "playerUuid": "string",
  "playerName": "string",
  "type": "string",
  "reason": "string",
  "durationMs": 0,
  "expiresAt": 0,
  "ipBased": false,
  "active": false,
  "ipAddress": "string",
  "issuerUuid": "string",
  "issuerName": "string",
  "issuedAt": 0
}

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/remove \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"punishmentId":0,"actorUuid":"string","actorName":"string","reason":"string"}'
// Revoke a single punishment by id (the actor is who lifted it).
hive.punishments().removePunishment(punishmentId, actorUuid, actorName, "Appeal granted");
POST /api/plugin/punishments/unban-by-name

Unban all active bans for a name

Revokes every active ban for a username; optionally also unbans their last-known IP.

Request body

application/json 
{
  "playerName": "string",
  "alsoUnbanLastIp": false,
  "actorUuid": "string",
  "actorName": "string",
  "reason": "string"
}

Responses

  • 200 OK.
  • 400 Bad Request
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/unban-by-name \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerName":"string","alsoUnbanLastIp":false,"actorUuid":"string","actorName":"string","reason":"string"}'
hive.punishments().unbanByName("Griefer", true /* also unban last IP */,
    actorUuid, actorName, "Appeal granted");
POST /api/plugin/punishments/unban-ip

Unban an IP

Revokes every active ban on an IP address.

Request body

application/json 
{
  "ipAddress": "string",
  "actorUuid": "string",
  "actorName": "string",
  "reason": "string"
}

Responses

  • 200 OK.
  • 400 Bad Request
200 response 
[
  {
    "id": 0,
    "playerUuid": "string",
    "playerName": "string",
    "type": "string",
    "reason": "string",
    "durationMs": 0,
    "expiresAt": 0,
    "ipBased": false,
    "active": false,
    "ipAddress": "string",
    "issuerUuid": "string",
    "issuerName": "string",
    "issuedAt": 0
  }
]

Request

~
curl -X POST http://localhost:8090/api/plugin/punishments/unban-ip \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ipAddress":"string","actorUuid":"string","actorName":"string","reason":"string"}'
hive.punishments().unbanIp("203.0.113.7", actorUuid, actorName, "Lifted");