Zum Inhalt

GET /banlist

Endpunkt: GET /v1/pdapi/banlist

Auth: Bearer-Token

Berechtigung: REST.Banlist.Read

Zweck

Liest Bann-Eintraege aus der Bannliste. Bannbezogene Daten werden in Banlist.json gespeichert, nicht in Config.json.

Pfadparameter

Keine.

Query-Parameter

  • active: true, false, or 1 to filter active state.
  • entryType: Nach Bann-Eintragstyp filtern.
  • userId: Filter by user ID.
  • ip or userIP: Filter by IP address.
  • issuerType, issuerName, issuerIP: Nach Aussteller-Metadaten filtern.
  • reason: Filter by reason text.
  • q: General text search.

Request-Body

Kein Request-Body.

Antwortschema

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.

Fehlerantworten

Fehlerantworten verwenden dieses Format:

{
    "Error": {
        "Code": "ERROR_CODE",
        "Message": "Für Menschen lesbare Nachricht",
        "Details": {}
    }
}
HTTP Fehlercode Wann es passiert
401 INVALID_TOKEN Der Authorization-Header fehlt, ist fehlerhaft oder passt zu keinem konfigurierten Bearer-Token.
403 MISSING_PERMISSION Das Token ist gültig, enthält aber nicht die Berechtigung für diesen Endpunkt.

Beispiele

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

Szenarien

  • 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.