API Documentation - UtopiaFPS.pl

Login required

To generate an API token, you must be logged in.

Getting started

The UtopiaFPS API provides programmatic access to server status information and penalty records. All responses are in JSON format and include cache headers for optimal performance.

Base URL

https://utopiafps.pl/api/v1

Rate limits

Public endpoints 30 requests per minute
Protected endpoints 60 requests per minute (API token required)

Authentication

Protected endpoints require an API token. Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Alternatively you can pass the token as a query parameter: ?api_token=YOUR_TOKEN

?api_token=YOUR_API_TOKEN

PUBLIC Server Endpoints

GET /servers

Retrieve a list of all servers with their current status.

Example response

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

Get detailed information about a specific server using its slug.

Example response

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

Example response

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

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

Example response

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

PROTECTED Penalty Endpoints

GET /penalties

Retrieve all penalties (bans, mutes, gags, silences, warnings) with optional filters.

Query parameters

type - Filter by penalty type (ban, mute, gag, silence, warn or empty for all)
status - Filter by status active expired unbanned
server_id - Filter by server ID
steamid - Filter by player SteamID64
admin_steamid - Filter by admin SteamID64
per_page - Results per page (default 50, max 100)
page - Page number

Example response

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

Retrieve a paginated list of bans with optional filters.

Query parameters

status - Filter by status active expired unbanned
server_id - Filter by server ID
steamid - Filter by player SteamID64
per_page - Results per page (default 50, max 100)
page - Page number

Example response

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

Retrieve a paginated list of bans with optional filters.

Query parameters

status - Filter by status
server_id - Filter by server ID
steamid - Filter by player SteamID64
type - Filter by type: gag, mute, silence
per_page - Results per page (default 50, max 100)
page - Page number

Response structure similar to bans endpoint

GET /warns

Retrieve a paginated list of bans with optional filters.

Query parameters

status - Filter by status
server_id - Filter by server ID
steamid - Filter by player SteamID64
per_page - Results per page (default 50, max 100)
page - Page number

PROTECTED User Lookup

GET /users/lookup

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

Query parameters

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.

Example response (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

Error responses

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

When the rate limit is exceeded, you will receive a 429 status code with retry information in the headers.

Cookie consent

Documentation API

Login required

Getting started

Base URL

Rate limits

Authentication

PUBLIC Server Endpoints

Example response

Example response

Example response

PUBLIC Player Roundsound

Example response

PROTECTED Penalty Endpoints

Query parameters

Example response

Query parameters

Example response

Query parameters

Response structure similar to bans endpoint

Query parameters

PROTECTED User Lookup

Query parameters

Example response (200)

Kody błędów

Error responses

401 Unauthorized

404 Not Found

429 Too Many Requests