Dokumentacja API

Wymagane logowanie

Aby wygenerować token API, musisz być zalogowany.

Pierwsze kroki

API UtopiaFPS umożliwia programowy dostęp do informacji o statusie serwerów oraz rekordów kar. Wszystkie odpowiedzi są w formacie JSON i zawierają nagłówki cache dla optymalnej wydajności.

Adres bazowy

https://utopiafps.pl/api/v1

Limity zapytań

Publiczne endpointy 30 żądań na minutę
Chronione endpointy 60 żądań na minutę (wymagany token API)

Uwierzytelnianie

Chronione endpointy wymagają tokenu API. Dołącz swój token w nagłówku Authorization:

Authorization: Bearer YOUR_API_TOKEN

Alternatywnie możesz przekazać token jako parametr zapytania: ?api_token=TWÓJ_TOKEN

?api_token=YOUR_API_TOKEN

PUBLICZNE Endpointy serwerów

GET /servers

Pobierz listę wszystkich serwerów z ich aktualnym statusem.

Przykładowa odpowiedź

{
  "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}

Pobierz szczegółowe informacje o konkretnym serwerze za pomocą jego sluga.

Przykładowa odpowiedź

{
  "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).

Przykładowa odpowiedź

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

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

Przykładowa odpowiedź

{
  "success": true,
  "url": "https://utopiafps.pl/storage/roundsound/76561197961430531.mp3",
  "title": "my_track.mp3"
}

Pole url zawsze wskazuje na plik .mp3 pod ścieżką /storage/roundsound/{steamid64}.mp3. 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.

CHRONIONE Endpointy kar

GET /penalties

Pobierz wszystkie kary (bany, mute, gag, silence, ostrzeżenia) z opcjonalnymi filtrami.

Parametry zapytania

type - Filtruj według typu kary (ban, mute, gag, silence, warn lub puste dla wszystkich)
status - Filtruj według statusu: aktywny, wygasły, odbanowany
server_id - Filtruj według ID serwera
steamid - Filtruj według SteamID64 gracza
admin_steamid - Filtruj według SteamID64 admina
per_page - Wyniki na stronę (domyślnie 50, maks. 100)
page - Numer strony

Przykładowa odpowiedź

{
  "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

Pobierz stronicowaną listę banów z opcjonalnymi filtrami.

Parametry zapytania

status - Filtruj według statusu: aktywny, wygasły, odbanowany
server_id - Filtruj według ID serwera
steamid - Filtruj według SteamID64 gracza
per_page - Wyniki na stronę (domyślnie 50, maks. 100)
page - Numer strony

Przykładowa odpowiedź

{
  "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

Pobierz stronicowaną listę banów z opcjonalnymi filtrami.

Parametry zapytania

status - Filtruj według statusu
server_id - Filtruj według ID serwera
steamid - Filtruj według SteamID64 gracza
type - Filtruj według typu: gag, mute, silence
per_page - Wyniki na stronę (domyślnie 50, maks. 100)
page - Numer strony

Struktura odpowiedzi podobna do endpointu banów

GET /warns

Pobierz stronicowaną listę banów z opcjonalnymi filtrami.

Parametry zapytania

status - Filtruj według statusu
server_id - Filtruj według ID serwera
steamid - Filtruj według SteamID64 gracza
per_page - Wyniki na stronę (domyślnie 50, maks. 100)
page - Numer strony

CHRONIONE User Lookup

GET /users/lookup

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

Parametry zapytania

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.

Przykładowa odpowiedź (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

Odpowiedzi błędów

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

Gdy limit zapytań zostanie przekroczony, otrzymasz kod statusu 429 z informacjami o ponownej próbie w nagłówkach.

Zgoda na pliki cookies

Dostosuj

Wymagane logowanie

Pierwsze kroki

Adres bazowy

Limity zapytań

Uwierzytelnianie

PUBLICZNE Endpointy serwerów

Przykładowa odpowiedź

Przykładowa odpowiedź

Przykładowa odpowiedź

PUBLICZNE Player Roundsound

Przykładowa odpowiedź

CHRONIONE Endpointy kar

Parametry zapytania

Przykładowa odpowiedź

Parametry zapytania

Przykładowa odpowiedź

Parametry zapytania

Struktura odpowiedzi podobna do endpointu banów

Parametry zapytania

CHRONIONE User Lookup

Parametry zapytania

Przykładowa odpowiedź (200)

Kody błędów

Odpowiedzi błędów

401 Unauthorized

404 Not Found

429 Too Many Requests