API-Dokumentation - UtopiaFPS.pl

Anmeldung erforderlich

Um ein API-Token zu generieren, müssen Sie angemeldet sein.

Erste Schritte

Die UtopiaFPS-API bietet programmatischen Zugriff auf Serverstatusinformationen und Strafendatensätze. Alle Antworten sind im JSON-Format und enthalten Cache-Header für optimale Leistung.

Basis-URL

https://utopiafps.pl/api/v1

Ratenbegrenzungen

Öffentliche Endpunkte 30 Anfragen pro Minute
Geschützte Endpunkte 60 Anfragen pro Minute (API-Token erforderlich)

Authentifizierung

Geschützte Endpunkte erfordern ein API-Token. Geben Sie Ihr Token im Authorization-Header ein:

Authorization: Bearer YOUR_API_TOKEN

Alternativ können Sie das Token als Abfrageparameter übergeben: ?api_token=IHR_TOKEN

?api_token=YOUR_API_TOKEN

ÖFFENTLICH Server-Endpunkte

GET /servers

Rufen Sie eine Liste aller Server mit ihrem aktuellen Status ab.

Beispielantwort

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Server #1",
      "slug": "server-1",
      "hostname": "UtopiaFPS Server #1",
      "ip": "51.75.59.212:27015",
      "map": "de_dust2",
      "mode": "casual",
      "region": "pl",
      "players_count": 12,
      "max_players": 32,
      "is_online": true,
      "ping_ms": 25,
      "updated_at": "2025-01-23T12:34:56+00:00"
    }
  ],
  "meta": {
    "total": 5,
    "online": 3,
    "cached_at": "2025-01-23T12:34:56+00:00"
  }
}

GET /servers/{slug}

Erhalten Sie detaillierte Informationen zu einem bestimmten Server mithilfe seines Slugs.

Beispielantwort

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Server #1",
    "slug": "server-1",
    "hostname": "UtopiaFPS Server #1",
    "ip": "51.75.59.212:27015",
    "map": "de_dust2",
    "mode": "casual",
    "region": "pl",
    "players_count": 12,
    "max_players": 32,
    "is_online": true,
    "ping_ms": 25,
    "updated_at": "2025-01-23T12:34:56+00:00",
    "players": [
      { "name": "PlayerName1", "score": 150 },
      { "name": "PlayerName2", "score": 120 }
    ]
  },
  "meta": { "cached_at": "2025-01-23T12:34:56+00:00" }
}

GET /servers/{id}/players

Zwraca aktualną listę graczy podłączonych do serwera. Parametr {id} to numeryczne ID (nie slug).

Beispielantwort

{
  "success": true,
  "players": [
    { "name": "PlayerName1", "score": 150 },
    { "name": "PlayerName2", "score": 120 }
  ]
}

ÖFFENTLICH Player Roundsound

GET /players/{steamid64}/roundsound

Zwraca URL do przetworzonego roundsound'u gracza (gdy status = ready). Używane przez plugin CS2 do odtwarzania dźwięku po zakończeniu rundy.

Beispielantwort

{
  "success": true,
  "url": "https://utopiafpspl-assets.b-cdn.net/roundsound/76561197961430531.mp3?v=1760380000",
  "title": "my_track.mp3"
}

Pole url wskazuje na plik roundsound/{steamid64}.mp3 na CDN, z parametrem ?v= zmieniającym się przy każdym nowym dźwięku. Używaj URL-a dokładnie w tej postaci, nie składaj go samodzielnie. Plik jest przetworzony (normalizacja głośności, przycięcie długości).

Gdy gracz nie ma gotowego dźwięku, endpoint zwraca { "success": false, "url": null, "title": null } z kodem 200.

GESCHÜTZT Straf-Endpunkte

GET /penalties

Rufen Sie alle Strafen (Sperren, Stummschaltungen, Gags, Stille, Verwarnungen) mit optionalen Filtern ab.

Abfrageparameter

type - Nach Straftyp filtern (Bann, Stummschaltung, Gagging, Stille, Verwarnung oder leer für alle)
status - Nach Status filtern aktiv abgelaufen entbannt
server_id - Nach Server-ID filtern
steamid - Nach Spieler-SteamID64 filtern
admin_steamid - Nach Admin-SteamID64 filtern
per_page - Ergebnisse pro Seite (Standard 50, max. 100)
page - Seitennummer

Beispielantwort

{
  "success": true,
  "data": [
    {
      "penalty_type": "ban",
      "id": 123,
      "player_name": "PlayerName",
      "player_steamid": "76561198012345678",
      "admin_name": "AdminName",
      "admin_steamid": "76561198087654321",
      "reason": "Cheating",
      "duration": 0,
      "status": "ACTIVE",
      "server_id": 1,
      "created": "2025-01-23T12:00:00+00:00",
      "ends": null
    },
    {
      "penalty_type": "gag",
      "id": 456,
      "player_name": "AnotherPlayer",
      "player_steamid": "76561198099999999",
      "admin_name": "AdminName",
      "admin_steamid": "76561198087654321",
      "reason": "Spam",
      "duration": 3600,
      "status": "ACTIVE",
      "server_id": 1,
      "created": "2025-01-23T11:00:00+00:00",
      "ends": "2025-01-23T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 250,
    "per_page": 50,
    "last_page": 5,
    "counts": {
      "ban": 100,
      "gag": 50,
      "mute": 40,
      "silence": 30,
      "warn": 30
    },
    "cached_at": "2025-01-23T12:34:56+00:00"
  }
}

GET /bans

Rufen Sie eine seitenweise Liste der Sperren mit optionalen Filtern ab.

Abfrageparameter

status - Nach Status filtern aktiv abgelaufen entbannt
server_id - Nach Server-ID filtern
steamid - Nach Spieler-SteamID64 filtern
per_page - Ergebnisse pro Seite (Standard 50, max. 100)
page - Seitennummer

Beispielantwort

{
  "success": true,
  "data": [
    {
      "id": 123,
      "player_name": "PlayerName",
      "player_steamid": "76561198012345678",
      "admin_name": "AdminName",
      "admin_steamid": "76561198087654321",
      "reason": "Cheating",
      "duration": 0,
      "status": "ACTIVE",
      "server_id": 1,
      "created": "2025-01-23T12:00:00+00:00",
      "ends": null
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 150,
    "per_page": 50,
    "last_page": 3,
    "cached_at": "2025-01-23T12:34:56+00:00"
  }
}

GET /mutes

Rufen Sie eine seitenweise Liste der Sperren mit optionalen Filtern ab.

Abfrageparameter

status - Nach Status filtern
server_id - Nach Server-ID filtern
steamid - Nach Spieler-SteamID64 filtern
type - Filtern nach Typ: gag, mute, silence
per_page - Ergebnisse pro Seite (Standard 50, max. 100)
page - Seitennummer

Antwortstruktur ähnlich dem Sperr-Endpunkt

GET /warns

Rufen Sie eine seitenweise Liste der Sperren mit optionalen Filtern ab.

Abfrageparameter

status - Nach Status filtern
server_id - Nach Server-ID filtern
steamid - Nach Spieler-SteamID64 filtern
per_page - Ergebnisse pro Seite (Standard 50, max. 100)
page - Seitennummer

GESCHÜTZT User Lookup

GET /users/lookup

Wyszukiwanie użytkownika po Discord ID lub Steam ID64. Zwraca profil + status uprawnień i informację o aktywnym banie.

Abfrageparameter

discord_id - Discord ID użytkownika
steamid64 - Steam ID64 użytkownika

Wymagany dokładnie jeden z parametrów. Discord ID ma priorytet gdy podano oba.

Beispielantwort (200)

{
  "success": true,
  "user": {
    "nickname": "player_nick",
    "steamid64": "76561198012345678",
    "account_id": 12345678,
    "discord_id": "123456789",
    "discord_username": "PlayerUsername",
    "discord_avatar": "avatar_hash",
    "is_admin": false,
    "is_owner": false,
    "has_svip": true,
    "is_utopiaplus": false,
    "is_banned": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Kody błędów

400 - Brak parametru discord_id lub steamid64
404 - Użytkownik nie znaleziony

Fehlermeldungen

401 Unauthorized

{
  "success": false,
  "message": "API token is required"
}

404 Not Found

{
  "success": false,
  "message": "Server not found"
}

429 Too Many Requests

Wenn das Ratenlimit überschritten wird, erhalten Sie einen 429-Statuscode mit Wiederholungsinformationen in den Headern.

Cookie-Zustimmung

Anpassen

Dokumentation API

Anmeldung erforderlich

Erste Schritte

Basis-URL

Ratenbegrenzungen

Authentifizierung

ÖFFENTLICH Server-Endpunkte

Beispielantwort

Beispielantwort

Beispielantwort

ÖFFENTLICH Player Roundsound

Beispielantwort

GESCHÜTZT Straf-Endpunkte

Abfrageparameter

Beispielantwort

Abfrageparameter

Beispielantwort

Abfrageparameter

Antwortstruktur ähnlich dem Sperr-Endpunkt

Abfrageparameter

GESCHÜTZT User Lookup

Abfrageparameter

Beispielantwort (200)

Kody błędów

Fehlermeldungen

401 Unauthorized

404 Not Found

429 Too Many Requests