Minecraft Mod API

Public reference for API-key authenticated endpoints used by the Minecraft mod.

Base URL

• Production: https://whitelistsync.com

Authentication

Send this header with every request:

• X-API-KEY: <your-api-key>

If the key is missing or invalid, the API returns 401 Unauthorized.

Common responses

• Success responses are JSON.
• Invalid body/path input returns 400.
• Rate-limited requests return 429 Too Many Requests.

Endpoints

Connection check

GET /api/authentication

Validates your API key and returns the resolved server group.

Success (200):

{
  "serverGroupId": "<server-group-id>"
}

Whitelist

GET /api/whitelist

Returns currently whitelisted players.

Example item:

{
  "serverGroupId": "<server-group-id>",
  "name": "PlayerName",
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "isWhitelisted": true
}

POST /api/whitelist

Whitelist one player.

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

DELETE /api/whitelist/{uuid}

Remove one player from whitelist.

POST /api/whitelist/push

Bulk whitelist players.

[
  { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
]

Success (200):

{ "count": 3 }

Ops

GET /api/op

Returns currently opped players.

Example item:

{
  "serverGroupId": "<server-group-id>",
  "name": "PlayerName",
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "isOpped": true
}

POST /api/op

Op one player.

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

DELETE /api/op/{uuid}

De-op one player.

POST /api/op/push

Bulk op players.

[
  { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
]

Success (200):

{ "count": 3 }

Banned Players

GET /api/bannedplayer

Returns currently banned players.

Example item:

{
  "serverGroupId": "<server-group-id>",
  "name": "PlayerName",
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reason": "optional reason",
  "isBanned": true
}

POST /api/bannedplayer

Ban one player.

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reason": "optional reason"
}

DELETE /api/bannedplayer/{uuid}

Unban one player.

POST /api/bannedplayer/push

Bulk ban players.

[
  {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "reason": "optional reason"
  }
]

Success (200):

{ "count": 3 }

Banned IPs

GET /api/bannedip

Returns currently banned IPs.

Example item:

{
  "serverGroupId": "<server-group-id>",
  "ip": "203.0.113.5",
  "reason": "optional reason",
  "isBanned": true
}

POST /api/bannedip

Ban one IP address.

{
  "ip": "203.0.113.5",
  "reason": "optional reason"
}

DELETE /api/bannedip/{ip}

Unban one IP.

POST /api/bannedip/push

Bulk ban IPs.

[
  {
    "ip": "203.0.113.5",
    "reason": "optional reason"
  }
]

Success (200):

{ "count": 3 }

Quick test

curl -X GET \
  -H "X-API-KEY: <api-key>" \
  https://whitelistsync.com/api/whitelist