API

Read public Gameserver data or securely manage your own Gameservers from a trusted server-side application.

sad

Public access

Unauthenticated GET requests return public data and can be used directly in a browser.

Authenticated management

API keys identify an authenticated user.

Request limits

Unauthenticated: up to 60 requests per minute and 5,000 per day for each IP address.

Authenticated: up to 300 requests per minute and 25,000 per day. All API keys of one user share this limit.

Quick start

Base URL
https://forum.primearea.net/api/rpc/game-server-viewer/v1

Public access

Public GET responses support cross-origin browser access and never expose credentials, raw query data or private configuration. Public reads do not trigger a live server query.

curl --request GET \
	--header "Accept: application/json" \
	'https://forum.primearea.net/api/rpc/game-server-viewer/v1/servers?status=online&limit=10'

Responses and caching

Responses use JSON and include short cache lifetimes, ETags and, where applicable, Last-Modified. Conditional requests can return 304 Not Modified. Exceeded request limits return HTTP 429 with Retry-After.

Documentation v1

Base URL
https://forum.primearea.net/api/rpc/game-server-viewer/v1
Method Endpoint Purpose
GET/API version and links to all resources.
GET/gamesList of all enabled games.
GET/categoriesList of all publicly visible categories.
GET/serversPaginated and filterable list of public Gameservers.
GET/servers/{id}Public details of a single Gameserver.
GET/servers/{id}/statusCurrently stored status of a single Gameserver.
GET/servers/{id}/statisticsAggregated statistics for up to 30 days, if enabled.

Query parameters

Only the documented parameters are accepted. Unsupported parameters return a validation error instead of being silently ignored.

All public GET endpoints accept the optional fields parameter, for example fields=status,statistics.periods.72h on a server detail request. Comma-separated paths select whole sections or nested fields within data; list endpoints apply the selection to each item. On the API index, paths address documentation or resources directly. Omit fields for the full response. Metadata and pagination stay intact. Invalid paths are rejected; at most 64 paths and 2048 characters are allowed. Selection never overrides permissions or visibility settings.

GET /games, /categories, /servers/{id}, /status

Selects a supported response language, for example en or de.

language=de

GET /servers

Filters the Gameserver list by game identifier, category ID, status or minimum update time.

  • game=identifier
  • category=integer > 0
  • status=online|offline|maintenance
  • updatedSince=Unix timestamp

Controls page, page size and sorting. The page size is limited to 100 entries.

  • page=1..1000 (1)
  • limit=1..100 (20)
  • sort=id|name|players|updated|created (id)
  • order=asc|desc (desc)

GET /servers/{id}/statistics

Selects the statistics period, grouping and state. The maximum period is 30 days.

  • days=1..30 (1)
  • from=Unix timestamp + to=Unix timestamp
  • interval=auto|hour|day (auto)
  • state=all|online|offline|maintenance (all)

Responses

Server data

Existing fields remain unchanged. name is the configured name; query.name is the queried server name. query.parameters contains selected additional game information with a label and typed value (including numbers and booleans). Unavailable values are null. status.connection adds connection data; an address alias keeps the actual host and port hidden. The detail response also includes statistics.periods for 72h, 7d and 30d when API statistics are allowed. availabilityPercent is the online share of recorded measurements, not continuously monitored time. averagePlayers uses measurements with known player counts. Sample counts and first and last sample timestamps describe the available data. Missing measurements produce null rather than 0; the summary is cached for five minutes. Query data follows the server-page selection; its values are null while offline.

In detailed server responses, status.players.average is the average player count across all retained measurements with known player counts. statistics.overall provides the history range and sample counts. Unknown player counts are excluded; known counts of 0 are included. If statistics are unavailable or player information is hidden, the average is null. List and status-only responses remain unchanged.

  • 200 OK / 201 Created
  • 304 Not Modified
  • 400 Bad Request
  • 401 Unauthorized / 403 Forbidden
  • 404 Not Found
  • 429 Too Many Requests + Retry-After

Errors

Error responses use a consistent JSON structure with a type, code, message and affected parameter.

{
	"type": "invalid_request_error",
	"code": "invalid",
	"message": "...",
	"param": "..."
}

Request tester

Select an endpoint, add optional query parameters and execute a same-origin GET request.

Enter parameters without a leading question mark, separated by &.
Request URL
https://forum.primearea.net/api/rpc/game-server-viewer/v1?language=en