Документация API

Требуется вход

Чтобы создать API-токен, вы должны войти в аккаунт.

Начало работы

API UtopiaFPS предоставляет программный доступ к информации о статусе серверов и записям о наказаниях. Все ответы в формате JSON и включают заголовки кэширования для оптимальной производительности.

Базовый URL

https://utopiafps.pl/api/v1

Лимиты запросов

Публичные эндпоинты 30 запросов в минуту
Защищённые эндпоинты 60 запросов в минуту (требуется API-токен)

Аутентификация

Защищённые эндпоинты требуют API-токен. Укажите ваш токен в заголовке Authorization:

Authorization: Bearer YOUR_API_TOKEN

Также вы можете передать токен как параметр запроса: ?api_token=YOUR_TOKEN

?api_token=YOUR_API_TOKEN

ПУБЛИЧНО Эндпоинты серверов

GET /servers

Получить список всех серверов с их текущим статусом.

Пример ответа

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

Получить подробную информацию о конкретном сервере по его slug.

Пример ответа

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

Пример ответа

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

ПУБЛИЧНО 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.

Пример ответа

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

ЗАЩИЩЕНО Эндпоинты наказаний

GET /penalties

Получить все наказания (баны, муты, гаги, сайленсы, предупреждения) с дополнительными фильтрами.

Параметры запроса

type - Фильтр по типу наказания (ban, mute, gag, silence, warn или пусто для всех)
status - Фильтр по статусу: активен, истёк, разбанен
server_id - Фильтр по ID сервера
steamid - Фильтр по SteamID64 игрока
admin_steamid - Фильтр по SteamID64 админа
per_page - Результатов на странице (по умолчанию 50, макс. 100)
page - Номер страницы

Пример ответа

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

Получить постраничный список банов с дополнительными фильтрами.

Параметры запроса

status - Фильтр по статусу: активен, истёк, разбанен
server_id - Фильтр по ID сервера
steamid - Фильтр по SteamID64 игрока
per_page - Результатов на странице (по умолчанию 50, макс. 100)
page - Номер страницы

Пример ответа

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

Получить постраничный список банов с дополнительными фильтрами.

Параметры запроса

status - Фильтр по статусу
server_id - Фильтр по ID сервера
steamid - Фильтр по SteamID64 игрока
type - Фильтр по типу: gag, mute, silence
per_page - Результатов на странице (по умолчанию 50, макс. 100)
page - Номер страницы

Структура ответа аналогична эндпоинту банов

GET /warns

Получить постраничный список банов с дополнительными фильтрами.

Параметры запроса

status - Фильтр по статусу
server_id - Фильтр по ID сервера
steamid - Фильтр по SteamID64 игрока
per_page - Результатов на странице (по умолчанию 50, макс. 100)
page - Номер страницы

ЗАЩИЩЕНО User Lookup

GET /users/lookup

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

Параметры запроса

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.

Пример ответа (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

Ответы с ошибками

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

При превышении лимита запросов вы получите код статуса 429 с информацией о повторной попытке в заголовках.

Согласие на cookie

Настроить

Документация API

Требуется вход

Начало работы

Базовый URL

Лимиты запросов

Аутентификация

ПУБЛИЧНО Эндпоинты серверов

Пример ответа

Пример ответа

Пример ответа

ПУБЛИЧНО Player Roundsound

Пример ответа

ЗАЩИЩЕНО Эндпоинты наказаний

Параметры запроса

Пример ответа

Параметры запроса

Пример ответа

Параметры запроса

Структура ответа аналогична эндпоинту банов

Параметры запроса

ЗАЩИЩЕНО User Lookup

Параметры запроса

Пример ответа (200)

Kody błędów

Ответы с ошибками

401 Unauthorized

404 Not Found

429 Too Many Requests