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.

Building a plugin?

If you're a plugin developer integrating with the API, learn how to tag your requests with a provider identifier for analytics and attribution.

Plugin Developer →

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
GET /v1/plugins/checkbans	Plan daily limit	24 hours	API key
POST /v1/plugin/bans	Plan daily limit	24 hours	API key
DELETE /v1/plugin/bans/:id	Plan daily limit	24 hours	API key
POST /v1/appeals	3	1 hour	IP address
POST /v1/servers/:slug/whitelist-requests	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.
PLAYER_NOT_BANNED	422	Whitelist request rejected because no ACTIVE or PENDING ban exists for the provided UUID.
ALREADY_WHITELISTED	409	The UUID is already whitelisted for that server.
WHITELIST_REQUEST_EXISTS	409	An OPEN whitelist request already exists for that UUID on that server.
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. For banned responses, it also includes whitelisted and a server-specific whitelistRequestUrl that includes the ban short ID. 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. Other servers continue to receive isBanned: false until there is an ACTIVE ban from a Verified server.

Whitelist lookup is ban-only

Server whitelist checks are only evaluated when a ban is returned. If the player is clear (isBanned: false), no whitelist lookup is performed.

POST/v1/plugin/check

API Key1,000 requests / minute

Request body (JSON)

Parameter	Type	Required	Description
username	string	Yes	The player's in-game username.
uuid	string	Yes	The player's UUID.
provider	string	No	Plugin identifier for analytics attribution (e.g. "MyPlugin"). Max 64 characters. See the Plugin Developer guide for details.

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 from verified server)

{
  "data": {
    "isBanned": true,
    "whitelisted": false,
    "whitelistRequestUrl": "https://hytalebanlist.org/whitelist/my-server/Q7K2M9",
    "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,
    "whitelisted": false,
    "whitelistRequestUrl": "https://hytalebanlist.org/whitelist/my-server/Q7K2M9",
    "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
}

Banned but whitelisted for your server

{
  "data": {
    "isBanned": true,
    "whitelisted": true,
    "whitelistRequestUrl": "https://hytalebanlist.org/whitelist/my-server/Q7K2M9",
    "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,
      "appealUrl": "https://hytalebanlist.org/appeal/ban_abc123"
    }
  },
  "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"}'

Check Server Bans

Returns active, non-expired bans submitted by the authenticated server. This is useful for syncing a server's local moderation state, rebuilding caches after restart, or auditing bans from your plugin panel.

GET/v1/plugins/checkbans

API KeyCounted against your plan's daily limit

Query Parameters

Parameter	Type	Required	Description
provider	string	No	Your plugin or software identifier (e.g. "MyPlugin"). Counted as a check in provider analytics.

Response

200 OK

{
  "data": {
    "bans": [
      {
        "id": "ban_xyz789",
        "shortId": "Q7K2M9",
        "playerId": "player_abc123",
        "serverId": "server_123",
        "reason": "Cheating - fly hacks",
        "status": "ACTIVE",
        "source": "PLUGIN_AUTO",
        "submittedBy": "console",
        "expiresAt": null,
        "evidenceUrls": [],
        "notes": null,
        "reviewedBy": null,
        "createdAt": "2026-03-04T14:12:33.120Z",
        "updatedAt": "2026-03-04T14:12:33.120Z",
        "player": {
          "id": "player_abc123",
          "username": "BadActor42",
          "uuid": "2f7d2a19-44de-4c3a-92fc-0a77f6d2c8f1"
        },
        "appeal": null,
        "appealUrl": "https://hytalebanlist.org/appeal/Q7K2M9"
      }
    ]
  },
  "error": null
}

Example

cURL

curl -X GET 'https://api.hytalebanlist.org/v1/plugins/checkbans?provider=MyPlugin' \
  -H "X-Api-Key: YOUR_API_KEY"

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	Yes	The player's UUID.
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.
provider	string	No	Plugin identifier for analytics attribution (e.g. "MyPlugin"). Max 64 characters. Stored on the ban record and visible in the admin dashboard.

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.

Request body (JSON, optional)

Parameter	Type	Required	Description
provider	string	No	Plugin identifier for analytics attribution (e.g. "MyPlugin"). Max 64 characters. Logged against the revoke action.

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 "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"provider": "MyPlugin"}'

Provider Field

If you are building a plugin or third-party integration that server owners install and configure with their own API key, you can include an optional provider field in your API requests. This tags each check, ban, and unban with your plugin's identity so usage can be tracked separately from the server's own calls.

Accepted on all plugin endpoints

provider is accepted as an optional JSON body field on POST /v1/plugin/check, POST /v1/plugin/bans, and DELETE /v1/plugin/bans/:id. It is always optional — omitting it never breaks anything.

Developer accounts coming soon

A dedicated developer section is in the works where you will be able to register and lock in a permanent provider name for your plugin. In the meantime, use a consistent identifier across all your requests so your usage is grouped correctly in the admin analytics.

Read the Plugin Developer guide →

Public API

The public endpoints expose ban data, whitelist-request intake, 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

Request Whitelist

Allows a banned player to request server-specific whitelist access for one server. This creates an OPEN request for the server owner to review from their dashboard. Requests are only accepted for UUIDs that currently have an ACTIVE or PENDING ban.

POST/v1/servers/:slug/whitelist-requests

No auth required3 requests / hour per IP

Path parameters

Parameter	Type	Required	Description
slug	string	Yes	Server slug receiving the whitelist request.

Request body (JSON)

Parameter	Type	Required	Description
uuid	string	Yes	Player UUID requesting whitelist access.
username	string	No	Optional player username for owner context.
contactEmail	string	Yes	Email address the owner can use to respond.
message	string	Yes	Reason/request details. Must be 10-5000 characters.

Response (201 Created)

Whitelist request created

{
  "data": {
    "id": "wreq_abc123",
    "serverId": "server_123",
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "username": "Steve",
    "contactEmail": "[email protected]",
    "message": "I understand the ban context and would like to appeal for this specific server.",
    "status": "OPEN",
    "ownerNote": null,
    "reviewedBy": null,
    "reviewedAt": null,
    "createdAt": "2026-03-04T18:55:00.000Z",
    "updatedAt": "2026-03-04T18:55:00.000Z"
  },
  "error": null
}

Example

cURL

curl -X POST https://api.hytalebanlist.org/v1/servers/my-server/whitelist-requests \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "username": "Steve",
    "contactEmail": "[email protected]",
    "message": "Please whitelist me for this server only."
  }'

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

Check Server Bans

Submit a Ban

Revoke a Ban

Provider Field

Public API

Look Up Player

Get Ban Details

Request Whitelist

Platform Statistics

Ready to integrate?