ZCS.LT API Documentation

Overview. The ZCS.LT API provides programmatic access to server statistics and management functions. The API base URL is https://zcs.lt/api.

API structure

The API is divided into two categories:

1. Public endpoints

Used by the frontend and do not require authentication:

• /api/servers/{server}/stats/* — server statistics endpoints

2. Authenticated endpoints (API v1)

For external integrations and require an API token:

• /api/v1/servers — server list
• /api/v1/meta/* — meta information (game types, categories, countries)
• /api/v1/servers/{server} — server details
• /api/v1/servers/{server}/votes — server votes

Authentication

Public endpoints

Public endpoints (/api/servers/{server}/stats/*) do not require authentication and can be used directly.

Authenticated endpoints

Endpoints under /api/v1/* require an API token. Generate it in your account: Profile → API access. Send the token on every request:

Authorization: YOUR_TOKEN

Or with the Bearer prefix (both work):

Authorization: Bearer YOUR_TOKEN

Rate limiting

• 60 requests per minute per IP address or authenticated user ID
• If you exceed the limit, you receive 429 Too Many Requests

Base URL

https://zcs.lt/api

Public: /api/servers/{server}/stats/*

Authenticated (v1): /api/v1/*

---

1. Server player statistics

Get server player statistics over a specified time period.

Endpoint:

GET /api/servers/{server}/stats/players

Parameter	Type	Required	Default	Description
server	integer	Yes	—	Server ID (route parameter)
days	integer	No	14	Number of days (1–365)
granularity	string	No	auto	day, hour, or 15min (auto-selected based on days)

Examples:

GET https://zcs.lt/api/servers/1/stats/players?days=14
GET https://zcs.lt/api/servers/1/stats/players?days=7
GET https://zcs.lt/api/servers/1/stats/players?days=1
GET https://zcs.lt/api/servers/1/stats/players?days=30

Response when days > 1 (daily granularity):

{
  "server_id": 1,
  "range": {
    "from": "2025-11-01",
    "to": "2025-11-15",
    "days": 14
  },
  "granularity": "day",
  "series": [
    {
      "date": "2025-11-01",
      "max": 45,
      "average": 32,
      "min": 15,
      "peak_hour": 20,
      "members_max": null,
      "members_average": null,
      "members_min": null
    },
    {
      "date": "2025-11-02",
      "max": 48,
      "average": 35,
      "min": 18,
      "peak_hour": 21,
      "members_max": null,
      "members_average": null,
      "members_min": null
    }
  ]
}

Response when days = 1 (15-minute granularity):

{
  "server_id": 1,
  "range": {
    "from": "2025-11-15T00:00:00+00:00",
    "to": "2025-11-15T23:59:59+00:00",
    "days": 1
  },
  "granularity": "15min",
  "interval_minutes": 15,
  "series": [
    {
      "date": "00:00",
      "timestamp": "2025-11-15T00:00:00+00:00",
      "max": 25,
      "average": 20,
      "min": 15,
      "peak_hour": 0,
      "members_max": null,
      "members_average": null,
      "members_min": null
    }
  ]
}

Field descriptions:

• server_id — server ID
• range.from / range.to — start and end of the period
• range.days — number of days
• granularity — day or 15min
• series — array of points: date, max, average, min, peak_hour (hour 0–23 with most players)
• members_max, members_average, members_min — for Discord servers; null for game servers
• timestamp — ISO 8601 (only for 15-minute granularity)

---

2. Server map statistics

Get map usage statistics over a period.

Endpoint:

GET /api/servers/{server}/stats/maps

Parameter	Type	Required	Default	Description
server	integer	Yes	—	Server ID
days	integer	No	14	Days (1–365)

Examples:

GET https://zcs.lt/api/servers/1/stats/maps?days=14
GET https://zcs.lt/api/servers/1/stats/maps?days=7
GET https://zcs.lt/api/servers/1/stats/maps?days=1

Response when days > 1:

{
  "server_id": 1,
  "range": {
    "from": "2025-11-01",
    "to": "2025-11-15",
    "days": 14
  },
  "granularity": "day",
  "maps": [
    {
      "map": "de_dust2",
      "plays": 245,
      "average_percentage": 45.5
    },
    {
      "map": "de_mirage",
      "plays": 180,
      "average_percentage": 33.3
    }
  ]
}

Response when days = 1:

{
  "server_id": 1,
  "range": {
    "from": "2025-11-15 00:00:00",
    "to": "2025-11-15 23:59:59",
    "days": 1
  },
  "granularity": "hour",
  "maps": [
    {
      "map": "de_dust2",
      "plays": 12,
      "average_percentage": 50.0
    }
  ]
}

Fields: maps is sorted by plays descending. Each row: map, plays, average_percentage.

---

3. Server player heatmap

Hour-of-day heatmap statistics.

Endpoint:

GET /api/servers/{server}/stats/heatmap

Parameter	Type	Required	Default	Description
server	integer	Yes	—	Server ID
days	integer	No	14	Days (1–365)

Example:

GET https://zcs.lt/api/servers/1/stats/heatmap?days=7

Response (shape):

{
  "server_id": 1,
  "range": {
    "from": "2025-11-08",
    "to": "2025-11-15",
    "days": 7
  },
  "granularity": "hour",
  "heatmap": {
    "2025-11-08": {
      "0": {
        "average": 15,
        "max": 20,
        "samples": 4,
        "map": null
      },
      "12": {
        "average": 35,
        "max": 45,
        "samples": 4,
        "map": null
      }
    }
  },
  "daily_peak": {
    "2025-11-08": 50,
    "2025-11-09": 48
  }
}

Dates are keys (YYYY-MM-DD); hours are keys 0–23. Each hour: average, max, samples, map (may be null). daily_peak is max players per day.

---

Authenticated endpoints (API v1)

All of the following require Authorization: YOUR_TOKEN (or Bearer).

4. Server list

Endpoint: GET /api/v1/servers

Parameter	Type	Default	Description
user_servers_only	boolean	true	Only servers linked to your account
server_ids	string	—	Comma-separated IDs, e.g. 1,2,3
search	string	—	Search hostname or description
status	string	—	online or offline
is_vip	boolean	—	VIP only
game_type_id	integer	—	Filter by game type
category_id	integer	—	Filter by category
country_code	string	—	Country code
sort	string	created_at	created_at, current_players, votes_count
order	string	desc	asc or desc
page	integer	1	Page number
per_page	integer	15	Page size (max 100)

Examples:

curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers"
curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers?user_servers_only=false"
curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers?search=zombie&status=online&is_vip=true"
curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers?server_ids=1,2,3"

Response (shape):

{
  "data": [
    {
      "id": 1,
      "hostname": "My Server",
      "description": "Server description",
      "ip": "192.168.1.1",
      "port": 27015,
      "display_address": "192.168.1.1:27015",
      "status": "online",
      "current_players": 25,
      "max_players": 32,
      "current_map": "de_dust2",
      "is_vip": false,
      "game_type": {
        "id": 1,
        "name": "Counter-Strike 1.6",
        "slug": "cs16"
      },
      "categories": [
        {
          "id": 1,
          "name": "Zombie",
          "slug": "zombie"
        }
      ],
      "votes_count": 42,
      "url": "https://zcs.lt/servers/cs16/my-server"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 75
  },
  "meta": {
    "game_types": [],
    "categories": [],
    "user_servers_only": true
  }
}

5. Meta — game types

GET /api/v1/meta/game-types

{
  "data": [
    { "id": 1, "name": "Counter-Strike 1.6", "slug": "cs16" },
    { "id": 2, "name": "Minecraft", "slug": "minecraft" }
  ]
}

6. Meta — categories

GET /api/v1/meta/categories

{
  "data": [
    { "id": 1, "name": "Zombie", "slug": "zombie" },
    { "id": 2, "name": "Surf", "slug": "surf" }
  ]
}

7. Meta — countries

GET /api/v1/meta/countries

{
  "data": ["US", "GB", "DE", "FR"]
}

8. Server details

GET /api/v1/servers/{server}

curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers/1"

{
  "id": 1,
  "slug": "my-server",
  "hostname": "My Server",
  "description": "Server description",
  "ip": "192.168.1.1",
  "dns_name": null,
  "port": 27015,
  "query_port": 27015,
  "display_address": "192.168.1.1:27015",
  "country_code": "US",
  "status": "online",
  "current_players": 25,
  "max_players": 32,
  "bot_players": 0,
  "current_map": "de_dust2",
  "is_vip": false,
  "vip_expires_at": null,
  "join_url": "steam://connect/192.168.1.1:27015",
  "discord_invite_code": null,
  "discord_invite_url": null,
  "first_seen_at": "2025-01-01T00:00:00+00:00",
  "last_checked_at": "2025-12-06T12:00:00+00:00",
  "last_online_at": "2025-12-06T12:00:00+00:00",
  "game_type": {
    "id": 1,
    "name": "Counter-Strike 1.6",
    "slug": "cs16"
  },
  "categories": [
    {
      "id": 1,
      "name": "Zombie",
      "slug": "zombie"
    }
  ]
}

9. Server votes

GET /api/v1/servers/{server}/votes

curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers/1/votes"

{
  "server_id": 1,
  "total_votes": 42,
  "votes_today": 5,
  "votes_this_week": 15,
  "votes_this_month": 30
}

10. User information (web session / Sanctum)

GET /api/user — typically used with a Sanctum session or SPA token, not the same as the public API v1 listing token unless your app is configured to unify them.

{
  "id": 1,
  "name": "User Name",
  "email": "[email protected]"
}

---

Error handling

• 200 OK — success
• 404 Not Found — server or resource not found
• 429 Too Many Requests — rate limit
• 500 Internal Server Error — server error

Error body (example):

{
  "message": "Error message",
  "error": "Additional error information"
}

---

Finding the server ID

• Open the server page: https://zcs.lt/servers/{game}/{slug} — ID may appear in page metadata or HTML.
• Or call GET /api/v1/servers?search=... with your API token and read data[].id.

---

Examples — cURL

Public (no token)

curl "https://zcs.lt/api/servers/1/stats/players?days=14"
curl "https://zcs.lt/api/servers/1/stats/maps?days=7"
curl "https://zcs.lt/api/servers/1/stats/heatmap?days=7"

Authenticated (token)

curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers"
curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/meta/game-types"
curl -H "Authorization: YOUR_TOKEN" "https://zcs.lt/api/v1/servers/1"

---

Examples — JavaScript (fetch)

Public

fetch('https://zcs.lt/api/servers/1/stats/players?days=14')
  .then(r => r.json())
  .then(console.log);

Authenticated

const API_TOKEN = 'YOUR_TOKEN';
const API_BASE = 'https://zcs.lt/api/v1';

fetch(`${API_BASE}/servers`, {
  headers: { 'Authorization': API_TOKEN }
}).then(r => r.json()).then(console.log);

---

Notes

• Data updates: statistics refresh about every 5 minutes, with backoff for unreachable servers.
• Discord servers: members_* fields in player stats may be populated; for other servers they are null.
• Empty results: if there is no data for the period, series or maps may be empty arrays.
• Granularity: for player stats, days = 1 uses 15-minute granularity; days > 1 uses daily. Heatmap uses hourly granularity.
• Date formats: daily points use YYYY-MM-DD; 15-minute points use ISO 8601 timestamps with timezone.

Version

This page reflects the API as documented for ZCS.LT. For the latest behaviour, test responses against your environment.

---

Support

Questions about the API: [email protected].