List Servers

Endpoint

GET /api/v1/servers

Query parameters

• limit number of records to return
• search free text filter (IP, IP:PORT, or description text)
• description description-only text filter
• version protocol version filter
• onlineOnly set to true for recently seen online servers
• minPlayers minimum online player count
• maxPlayers maximum online player count
• countryCodes comma-separated ISO country codes (for example US,DE,BR)
• cursorUpdatedAt cursor timestamp (ISO string, used with cursor fields below)
• cursorIpAddress cursor IP as signed 32-bit integer for stable ordering
• cursorPort cursor port for stable ordering
• offset fallback offset pagination (only used when cursor params are not provided)

Pagination behavior

• Preferred mode is cursor pagination via cursorUpdatedAt, cursorIpAddress, and cursorPort.
• Offset pagination is still supported for compatibility.
• Response metadata includes meta.hasMore.

Example

curl -X GET "https://slowstack.tv/api/v1/servers?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cursor example

curl -X GET "https://slowstack.tv/api/v1/servers?limit=20&cursorUpdatedAt=2026-02-21T09:36:42.332Z&cursorIpAddress=1981539350&cursorPort=25565" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code examples

JavaScript

const params = new URLSearchParams({
  limit: '20',
  cursorUpdatedAt: '2026-02-21T09:36:42.332Z',
  cursorIpAddress: '1981539350',
  cursorPort: '25565'
});

const response = await fetch(`https://slowstack.tv/api/v1/servers?${params.toString()}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const result = await response.json();
console.log(result.data[0]?.ipAddress, result.meta?.hasMore);

Python

import requests

params = {
    "limit": 20,
    "cursorUpdatedAt": "2026-02-21T09:36:42.332Z",
    "cursorIpAddress": 1981539350,
    "cursorPort": 25565,
}

response = requests.get(
    "https://slowstack.tv/api/v1/servers",
    params=params,
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=10,
)
response.raise_for_status()

result = response.json()
print(result["data"][0]["ipAddress"], result["meta"].get("hasMore"))

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://slowstack.tv/api/v1/servers?limit=20"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() != 200) {
    throw new RuntimeException("Request failed: " + response.statusCode());
}

System.out.println(response.body());

Response

{
  "data": [
    {
      "ipAddress": 1981539350,
      "port": 25565,
      "version": "1.21.5",
      "maxPlayers": 20,
      "players": 0,
      "description": "A Minecraft Server",
      "descriptionExtra": "",
      "updatedAt": "2026-02-21T10:03:52.647Z",
      "favicon": "https://.../6545018510055934522.png"
    }
  ],
  "meta": {
    "hasMore": true
  }
}

ipAddress values are signed 32-bit integers. See IP Address Integer Format for conversion examples in JavaScript, Python, and Java.