API documentation
Version 1 exposes real-time public game-server queries. GameDig runs only on the server. No status value is fabricated when a game server does not return it.
Authentication and limits
The current public endpoints require no API key. Requests are limited to RATE_LIMIT_PER_MINUTE (30 by default) per client IP. One query request may contain exactly one query port. API-key persistence is prepared in Prisma but is not exposed yet.
Query a server
POST/api/v1/query
Query one public server on the exact query port you provide. The game port is not inferred or scanned.
Request body
{
"game": "fivem",
"host": "play.example.com",
"ports": [30120]
}game is a slug from GET /api/v1/games; host is an IPv4/IPv6 address or DNS hostname; ports contains exactly one integer from 1 to 65535.
Successful response
{
"success": true,
"data": {
"status": "online",
"game": "fivem",
"host": "play.example.com",
"port": 30120,
"ping": 42,
"server": { "name": "Example RP", "map": "Los Santos", "version": null },
"players": { "online": 64, "max": 128 }
}
}Games and health
GET/api/v1/games
Lists the supported GameDig catalogue, including recommended game/query ports, protocol and GameDig notes when available.
GET/api/v1/games/{slug}
Returns one game definition.
GET/api/v1/health
Returns service health and the current timestamp.
Errors and security
Errors always use { "success": false, "error": { "code": "…", "message": "…" } }. Possible codes: INVALID_GAME, INVALID_HOST, INVALID_PORT, DNS_ERROR, SERVER_TIMEOUT, SERVER_OFFLINE, QUERY_FAILED, UNSUPPORTED_GAME, RATE_LIMITED, and SSRF_BLOCKED.
Private, loopback, link-local, Docker/Kubernetes and cloud-metadata destinations are rejected after DNS resolution. This API is for public game servers only.