REST API

Read-only JSON over HTTPS. Every request needs an API key that an admin created in the staff area.

Authentication

Send the key in the Authorization header. The X-API-Key header also works. Keys in the URL are not accepted, because URLs end up in logs.

Authorization: Bearer vlx_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys on your server. Never ship one inside a plugin jar, a website script or a Discord bot that others can read.

Limits

Each key has its own limit of requests per minute (60 unless an admin chose otherwise). Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Past the limit you get status 429 and a Retry-After header.

Errors

Errors use the same shape everywhere, with a stable code to program against:

{ "error": { "code": "missing_scope", "message": "This key lacks the \"coins:read\" scope. Ask an admin to add it." } }

Status	Codes
400	`bad_sort` `bad_type`
401	`missing_key` `key_invalid` `key_revoked` `key_expired`
403	`missing_scope`
404	`player_not_found` `punishment_not_found` `not_found`
429	`rate_limited` `too_many_attempts`
503	`ranks_unavailable`

Timestamps are ISO 8601 in UTC. Lists return data and a meta object with limit, offset and total. Player IP data is never part of the API.

Scopes

Scope Allows

status Read the network status and totals

players:read Read player profiles

coins:read Read coin balances, history and the top list

punishments:read Read bans and mutes

ranks:read Read ranks and the rank of a player

Scope	Allows
`status`	Read the network status and totals
`players:read`	Read player profiles
`coins:read`	Read coin balances, history and the top list
`punishments:read`	Read bans and mutes
`ranks:read`	Read ranks and the rank of a player

Endpoints

GET/api/v1/statusstatus

Health of the website and database, plus network totals.

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/status"

{
  "data": {
    "website": {
      "version": "1.0.0",
      "uptimeSeconds": 86400
    },
    "database": {
      "ok": true,
      "latencyMs": 2
    },
    "totals": {
      "players": 1842,
      "activePunishments": 37,
      "activeLast24h": 214
    }
  }
}

GET/api/v1/playersplayers:read

List players, newest activity first. Search by name prefix or part.

search: Part of a player name
sort: lastJoin (default), firstJoin, name or playtime
dir: desc (default) or asc
limit: 1-100, default 25
offset: Rows to skip

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/players"

{
  "data": [
    {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "Notch",
      "firstJoin": "2026-01-04T18:22:10.000Z",
      "lastJoin": "2026-10-05T20:01:44.000Z",
      "lastSeen": "2026-10-05T21:14:03.000Z",
      "playtimeMs": 183600000,
      "discordLinked": true
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 1842
  }
}

GET/api/v1/players/:idplayers:read

One player by UUID or name, with coins, rank and punishment counts.

id: UUID (with or without dashes) or player name

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/players/Notch"

{
  "data": {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch",
    "firstJoin": "2026-01-04T18:22:10.000Z",
    "lastJoin": "2026-10-05T20:01:44.000Z",
    "lastSeen": null,
    "playtimeMs": 183600000,
    "discordLinked": true,
    "coins": {
      "balance": 1250,
      "totalEarned": 4800
    },
    "rank": {
      "id": "vip",
      "display": "VIP",
      "weight": 20,
      "color": "#55FF55",
      "groups": []
    },
    "punishments": {
      "active": 0,
      "total": 1
    }
  }
}

GET/api/v1/players/:id/punishmentspunishments:read

All bans and mutes of one player, newest first.

id: UUID or player name
limit: 1-100, default 25
offset: Rows to skip

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/players/Notch/punishments"

{
  "data": [
    {
      "banId": "K7QX2M4PA9ZB",
      "type": "MUTE",
      "player": {
        "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
        "name": "Notch"
      },
      "reason": "Spam",
      "step": 1,
      "staff": "Alex",
      "createdAt": "2026-09-30T12:00:00.000Z",
      "expiresAt": "2026-09-30T13:00:00.000Z",
      "permanent": false,
      "active": false,
      "ipBan": false,
      "revokedAt": null,
      "revokeReason": null
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 1
  }
}

GET/api/v1/coins/topcoins:read

Richest players by current balance.

limit: 1-100, default 10

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/coins/top"

{
  "data": [
    {
      "position": 1,
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "Notch",
      "balance": 98500,
      "totalEarned": 120300
    }
  ]
}

GET/api/v1/coins/:idcoins:read

Coin balance of one player.

id: UUID or player name

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/coins/Notch"

{
  "data": {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch",
    "balance": 1250,
    "totalEarned": 4800,
    "updatedAt": "2026-10-05T20:10:00.000Z"
  }
}

GET/api/v1/coins/:id/logcoins:read

Coin history of one player, newest first.

id: UUID or player name
limit: 1-100, default 25
offset: Rows to skip

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/coins/Notch/log"

{
  "data": [
    {
      "delta": 50,
      "balance": 1250,
      "source": "daily",
      "reason": "Daily reward, day 3",
      "server": "Lobby",
      "createdAt": "2026-10-05T20:10:00.000Z"
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 14
  }
}

GET/api/v1/punishmentspunishments:read

Bans and mutes, newest first. Filter by type or only currently active ones.

type: BAN or MUTE
active: true = only punishments in force right now
limit: 1-100, default 25
offset: Rows to skip

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/punishments"

{
  "data": [
    {
      "banId": "K7QX2M4PA9ZB",
      "type": "BAN",
      "player": {
        "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
        "name": "Notch"
      },
      "reason": "Cheating",
      "step": 2,
      "staff": "Alex",
      "createdAt": "2026-10-01T09:00:00.000Z",
      "expiresAt": null,
      "permanent": true,
      "active": true,
      "ipBan": false,
      "revokedAt": null,
      "revokeReason": null
    }
  ],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 37
  }
}

GET/api/v1/punishments/:banIdpunishments:read

One punishment by its ban ID.

banId: The ban ID shown ingame, e.g. K7QX2M4PA9ZB

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/punishments/K7QX2M4PA9ZB"

{
  "data": {
    "banId": "K7QX2M4PA9ZB",
    "type": "BAN",
    "player": {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "Notch"
    },
    "reason": "Cheating",
    "step": 2,
    "staff": "Alex",
    "createdAt": "2026-10-01T09:00:00.000Z",
    "expiresAt": null,
    "permanent": true,
    "active": true,
    "ipBan": false,
    "revokedAt": null,
    "revokeReason": null
  }
}

GET/api/v1/ranksranks:read

All ranks with weight and color. Member counts need the LuckPerms database.

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/ranks"

{
  "data": [
    {
      "id": "owner",
      "display": "Owner",
      "weight": 100,
      "color": "#FF1F3D",
      "members": 2
    }
  ]
}

GET/api/v1/ranks/player/:idranks:read

Current rank of one player, including temporary ranks and when they end.

id: UUID or player name

curl -H "Authorization: Bearer $VELIUM_API_KEY" \
  "https://web.strafey.xyz/api/v1/ranks/player/Notch"

{
  "data": {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch",
    "rank": {
      "id": "vip",
      "display": "VIP",
      "weight": 20,
      "color": "#55FF55",
      "groups": [
        {
          "id": "vip",
          "expiresAt": "2026-12-01T00:00:00.000Z"
        }
      ]
    }
  }
}