UtopiaFPS
UtopiaFPS

Navigation

Developer API

Documentation API

RESTful API interface for server status and penalty data

Login required

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

Login via Steam

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

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 mutes 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 warnings 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

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.