REST API · v1

API Documentation

The Hytale Ban List API lets you integrate community ban protection directly into your Hytale server. Check whether a player is banned on join, submit new bans with screenshot evidence, and query the public ban database - all over a simple REST API.

Base URL

https://api.hytalebanlist.org

All API endpoints are prefixed with /v1. Responses are JSON. Use Content-Type: application/json for all request bodies unless specified otherwise.

Authentication

Plugin API endpoints require your server's API key, passed in the X-Api-Key request header. You receive your API key when you register your server. It is shown only once - store it securely.

Public API endpoints (player lookup, ban details, statistics) require no authentication and are freely accessible.

Example request header

X-Api-Key: hbl_a1b2c3d4e5f6...

Keep your API key secret

Your API key identifies your server and counts against your plan's daily API limit. Never expose it in client-side code or public repositories. Rotate it from your dashboard if it is ever compromised.

Response Format

Every response - success or failure - uses the same envelope structure. Check the error field first; if it is null, the request succeeded and data contains the result.

Success response

{
  "data": { ... },
  "error": null
}

Error response

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Player not found",
    "details": {}   // optional - validation errors, etc.
  }
}

Rate Limits

Rate limits are enforced per endpoint. When you exceed a limit the API returns HTTP 429 with a RATE_LIMITED error code and a message indicating when you can retry.

Endpoint	Limit	Window	Keyed by
POST /v1/plugin/check	1,000	1 minute	API key or IP
POST /v1/plugin/bans	Plan daily limit	24 hours	API key or IP
DELETE /v1/plugin/bans/:id	Plan daily limit	24 hours	API key or IP
POST /v1/appeals	3	1 hour	IP address
POST /v1/servers/register	5	24 hours	IP address

Error Codes

The error.code field is a stable machine-readable string you can match in your code.

Code	HTTP	Meaning
NOT_FOUND	404	The requested resource does not exist or is not publicly visible.
VALIDATION_ERROR	422	Request body failed validation. Check error.details for field-level errors.
MISSING_REASON	422	Ban submitted without a reason or tag. A PENDING ban is created and an appealUrl is returned. Follow the magicLink in data to supply the real reason via the web UI.
UNAUTHORIZED	401	Missing or invalid API key / auth token.
FORBIDDEN	403	Valid credentials but insufficient permissions for this action.
ALREADY_REVOKED	409	The ban has already been revoked and cannot be revoked again.
RATE_LIMITED	429	Too many requests. Retry after the time indicated in the error message.
INTERNAL_ERROR	500	Unexpected server error. Try again shortly or contact support.

Plugin API

These endpoints are designed for direct server integration. All Plugin API requests must include your X-Api-Key header. Verified servers have bans applied immediately; unverified servers submit bans for admin review.

Check Player Ban Status

Call this endpoint when a player attempts to join your server. Returns whether the player has an active ban, and if so, includes the ban reason and an appeal URL you can show them. Passing the player's UUID alongside their username gives the most reliable results.

Player record auto-created

Every check automatically creates a player record if one doesn't exist yet - no separate registration step needed. The resolved player (id, username, uuid) is always returned in the response so you can reference it in your own systems.

Your own pending bans are surfaced

If your server submitted a ban for a player that is still awaiting admin review (status: "PENDING"), this endpoint will return isBanned: true for your server specifically — even though the ban is not yet globally active. This lets you immediately enforce bans you submitted without waiting for verification. Anonymous servers (no API key) are matched by IP address using the same audit trail used for unbans.

POST/v1/plugin/check

API Key (optional)1,000 requests / minute

Request body (JSON)

Parameter	Type	Required	Description
username	string	Yes	The player's in-game username.
uuid	string	No	The player's UUID. Strongly recommended for accuracy - a player can change their username but not their UUID.

Response

Not banned

{
  "data": {
    "isBanned": false,
    "player": {
      "id": "player_abc123",
      "username": "Steve",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"  // null if not provided
    }
  },
  "error": null
}

Banned (globally active)

{
  "data": {
    "isBanned": true,
    "player": {
      "id": "player_abc123",
      "username": "Steve",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    },
    "ban": {
      "id": "ban_abc123",
      "reason": "Hacking - aimbot confirmed by server logs",
      "status": "ACTIVE",
      "submittedBy": "AdminMod",
      "expiresAt": null,          // null = permanent
      "appealUrl": "https://hytalebanlist.org/appeal/ban_abc123"
    }
  },
  "error": null
}

Banned (your pending ban — awaiting review)

{
  "data": {
    "isBanned": true,
    "player": {
      "id": "player_abc123",
      "username": "Steve",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    },
    "ban": {
      "id": "ban_xyz789",
      "reason": "Griefing",
      "status": "PENDING",        // submitted by your server, not yet globally active
      "submittedBy": "console",
      "expiresAt": null,
      "appealUrl": "https://hytalebanlist.org/appeal/ban_xyz789"
    }
  },
  "error": null
}

Example

cURL

curl -X POST https://api.hytalebanlist.org/v1/plugin/check \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"username": "Steve", "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"}'

Submit a Ban

Submit a ban for a player from your server. You can include up to 5 screenshot images as evidence. Bans from Verified servers become active immediately and are applied across the network. Bans from Unverified servers enter a pending queue for admin review.

POST/v1/plugin/bans

API KeyCounted against your plan's daily limit

Request

Send as application/json (text fields only) or multipart/form-data to include screenshot evidence.

Parameter	Type	Required	Description
username	string	Yes	The player's in-game username.
uuid	string	No	The player's UUID. Include whenever possible for reliable cross-server matching.
reason	string	No	Ban reason. Max 500 characters. If omitted (and no tag/tags provided), the API returns a 422 MISSING_REASON with a magicLink the server operator can use to supply the reason via the web UI. Known values (Hacking, Cheating, Exploiting, Griefing, Harassment, Toxic Behavior, Hate Speech, NSFW Content, Spam, Ban Evasion, Scamming, Inappropriate Username, Advertising) are preserved exactly. Anything else is stored as "Other: <your text>".
submittedBy	string	No	Username of the staff member who issued the ban (e.g. the moderator who ran the ban command). Max 64 characters. Defaults to "console" when not provided.
expiresAt	ISO 8601 datetime	No	Expiry date/time. Omit for a permanent ban.
screenshots	file (×5 max)	No	Screenshot evidence. JPEG, PNG, WebP, or GIF. Only accepted with multipart/form-data.

Response (201 Created)

Verified server - ban active immediately

{
  "data": {
    "ban": {
      "id": "ban_xyz789",
      "playerId": "player_abc",
      "serverId": "server_123",
      "reason": "Speed hacking",
      "status": "ACTIVE",
      "source": "PLUGIN_AUTO",
      "submittedBy": "AdminMod",
      "expiresAt": null,
      "evidenceUrls": ["https://cdn.hytalebanlist.org/evidence/shot1.png"],
      "createdAt": "2026-02-27T12:00:00.000Z"
    },
    "isPending": false,
    "appealUrl": "https://hytalebanlist.org/appeal/ban_xyz789"
  },
  "error": null
}

Unverified server - awaiting admin review

{
  "data": {
    "ban": { ... },
    "isPending": true,
    "appealUrl": "https://hytalebanlist.org/appeal/ban_xyz789"
  },
  "error": null
}

422 - No reason or tag supplied (magic link issued)

{
  "data": {
    "requiresReason": true,
    "magicLink": "https://hytalebanlist.org/submissions/ban-reason?token=...",
    "appealUrl": "https://hytalebanlist.org/appeal/ban_abc123"
  },
  "error": {
    "code": "MISSING_REASON",
    "message": "A reason or tag is required. Use the magic link to complete this ban."
  }
}

Magic link flow

When no reason, tag, or tags is provided, a PENDING ban is created immediately and an appealUrl is returned so you can notify the player right away. A short-lived magic link (valid 24 h) pointing to hytalebanlist.org/submissions/ban-reason is also returned. Open it in a browser to fill in the real reason — once submitted the ban is updated automatically and the page confirms whether it is active or pending review.

Examples

cURL - JSON (no screenshots)

curl -X POST https://api.hytalebanlist.org/v1/plugin/bans \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "username": "Griefer99",
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "reason": "Griefing - destroyed player base with TNT",
    "submittedBy": "AdminMod",
    "expiresAt": "2026-08-27T00:00:00.000Z"
  }'

cURL - multipart (with screenshots)

curl -X POST https://api.hytalebanlist.org/v1/plugin/bans \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "username=Griefer99" \
  -F "uuid=069a79f4-44e9-4726-a5be-fca90e38aaf5" \
  -F "reason=Griefing - destroyed player base with TNT" \
  -F "submittedBy=AdminMod" \
  -F "screenshots=@/path/to/screenshot1.png" \
  -F "screenshots=@/path/to/screenshot2.png"

Revoke a Ban

Revokes an existing ban that was submitted by your server. A revoked ban is no longer enforced across the network. You can only revoke bans that originated from your own server — attempting to revoke a ban submitted by a different server returns 403 FORBIDDEN.

DELETE/v1/plugin/bans/:id

API KeyCounted against your plan's daily limit

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The ban ID or shortId returned when the ban was created.

Response

200 OK - ban revoked

{
  "data": {
    "id": "ban_xyz789",
    "playerId": "player_abc",
    "serverId": "server_123",
    "reason": "Griefing - destroyed player base with TNT",
    "status": "REVOKED",
    "source": "PLUGIN_AUTO",
    "submittedBy": "AdminMod",
    "expiresAt": "2026-08-27T00:00:00.000Z",
    "evidenceUrls": [],
    "createdAt": "2026-02-27T12:00:00.000Z",
    "player": { "id": "player_abc", "username": "Griefer99", "uuid": "..." },
    "server": { "id": "server_123", "name": "My Hytale Server", "trustLevel": "VERIFIED" }
  },
  "error": null
}

403 - ban belongs to a different server

{
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to revoke this ban"
  }
}

409 - ban already revoked

{
  "data": null,
  "error": {
    "code": "ALREADY_REVOKED",
    "message": "This ban has already been revoked"
  }
}

Example

cURL

curl -X DELETE https://api.hytalebanlist.org/v1/plugin/bans/ban_xyz789 \
  -H "X-Api-Key: YOUR_API_KEY"

Public API

The public endpoints expose read-only ban data and platform statistics. No authentication is required. These endpoints power the public-facing search on hytalebanlist.org.

Look Up Player

Returns a player's profile and all of their publicly visible bans (status ACTIVE, REVOKED, or EXPIRED). The :identifier can be a username or a UUID.

GET/v1/players/:identifier

No auth required

Path parameters

Parameter	Type	Required	Description
identifier	string	Yes	Username or UUID of the player to look up.

Response

200 OK

{
  "data": {
    "id": "player_abc123",
    "username": "Steve",
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "bans": [
      {
        "id": "ban_xyz789",
        "reason": "Hacking - aimbot",
        "status": "ACTIVE",
        "source": "PLUGIN_AUTO",
        "expiresAt": null,
        "evidenceUrls": [],
        "createdAt": "2026-02-01T08:30:00.000Z",
        "server": {
          "id": "server_123",
          "name": "My Hytale Server",
          "trustLevel": "VERIFIED"
        }
      }
    ]
  },
  "error": null
}

Example

cURL

# Lookup by username
curl https://api.hytalebanlist.org/v1/players/Steve

# Lookup by UUID
curl "https://api.hytalebanlist.org/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Get Ban Details

Returns full details for a single ban, including the associated player, server, and any filed appeal. Only bans with status ACTIVE or REVOKED are publicly accessible. This endpoint is used by the appeal flow - the appeal form links directly to /appeal/:banId.

GET/v1/bans/:id

No auth required

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The ban ID.

Response

200 OK

{
  "data": {
    "id": "ban_xyz789",
    "reason": "Hacking - aimbot",
    "status": "ACTIVE",
    "source": "PLUGIN_AUTO",
    "expiresAt": null,
    "evidenceUrls": ["https://cdn.hytalebanlist.org/evidence/shot1.png"],
    "notes": null,
    "createdAt": "2026-02-01T08:30:00.000Z",
    "updatedAt": "2026-02-01T08:30:00.000Z",
    "player": {
      "id": "player_abc123",
      "username": "Steve",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    },
    "server": {
      "id": "server_123",
      "name": "My Hytale Server",
      "trustLevel": "VERIFIED"
    },
    "appeal": null   // or appeal object if one has been submitted
  },
  "error": null
}

Example

cURL

curl https://api.hytalebanlist.org/v1/bans/ban_xyz789

Platform Statistics

Returns aggregate platform statistics and the 50 most recent public bans. Useful for building dashboards or displaying community health metrics.

GET/v1/stats

No auth required

Response

200 OK

{
  "data": {
    "totalPlayers": 1482,
    "activeBans": 347,
    "openAppeals": 12,
    "registeredServers": 28,
    "recentBans": [
      {
        "id": "ban_xyz789",
        "reason": "Hacking - aimbot",
        "status": "ACTIVE",
        "source": "PLUGIN_AUTO",
        "expiresAt": null,
        "createdAt": "2026-02-27T10:15:00.000Z",
        "player": { "id": "...", "username": "Steve", "uuid": "..." },
        "server": { "id": "...", "name": "My Hytale Server" }
      }
      // ... up to 50 entries
    ]
  },
  "error": null
}

cURL

curl https://api.hytalebanlist.org/v1/stats

API Documentation

Authentication

Response Format

Rate Limits

Error Codes

Plugin API

Check Player Ban Status

Submit a Ban

Revoke a Ban

Public API

Look Up Player

Get Ban Details

Platform Statistics

Ready to integrate?