Skip to content

GET /banlist

Endpoint: GET /v1/pdapi/banlist

Auth: Bearer token

Permission: REST.Banlist.Read

Purpose

Reads ban records from the ban list. Ban-related data is stored in Banlist.json, not Config.json.

Path parameters

None.

Query parameters

  • active: true, false, or 1 to filter active state.
  • entryType: Filter by ban entry type.
  • userId: Filter by user ID.
  • ip or userIP: Filter by IP address.
  • issuerType, issuerName, issuerIP: Filter by issuer metadata.
  • reason: Filter by reason text.
  • q: General text search.

Request body

No request body.

Response schema

200 response schema

Field Type Description
Banlist object Banlist data after applying query filters.

Banlist object schema:

Field Type Description
Version integer Banlist file format version.
BannedMessage string Message shown to banned players.
UserEntries object[] User ban entries that match the supplied filters.
IPEntries object[] IP ban entries that match the supplied filters.

UserEntries[] item schema:

Field Type Description
UserId string Banned user ID.
Active boolean Whether the ban is currently active.
BannedBy object Issuer data for the ban action.
UnbannedBy object Issuer data for the unban action, when present.

IPEntries[] item schema:

Field Type Description
IP string Banned IP address.
Active boolean Whether the ban is currently active.
BannedBy object Issuer data for the ban action.
UnbannedBy object Issuer data for the unban action, when present.

Issuer object schema:

Field Type Description
Type string Issuer type, such as rest, player, or system.
NameValue string Issuer name, user ID, token, or type fallback.
IP string Issuer IP address metadata.
Reason string Reason recorded for the action.
Timestamp object UTC timestamp components for the action.

Timestamp object schema:

Field Type Description
UTC integer Unix timestamp in seconds.
Year integer UTC year.
Month integer UTC month.
Day integer UTC day of month.
Hour integer UTC hour.
Min integer UTC minute.
Sec integer UTC second.
Msec integer Millisecond component.

Error responses

Error bodies use this shape:

{
    "Error": {
        "Code": "ERROR_CODE",
        "Message": "Human-readable message",
        "Details": {}
    }
}
HTTP Error code When it happens
401 INVALID_TOKEN The Authorization header is missing, malformed, or does not match a configured bearer token.
403 MISSING_PERMISSION The token is valid, but it does not include this endpoint permission.

Examples

List all ban records

GET /v1/pdapi/banlist

Find active records for a Steam user

GET /v1/pdapi/banlist?active=true&userId=steam_76561198012345678

Search records by IP

GET /v1/pdapi/banlist?ip=203.0.113.42

Scenarios

  • Check whether a player or IP is currently banned.
  • Search by reason or issuer before unbanning.
  • Build a moderation dashboard that reads from Banlist.json through the API.