SimTX API v24/Server directory

The server directory lists the SimTX game servers that are currently online, with the host name and TCP port a client should connect to. It is the starting point for every game connection.

Request

GET /api/v1/servers

Requires a bearer credential (an access credential or a personal credential). Any scope is sufficient. Rate limit: 120 requests per minute per IP address.

curl -s https://auth.simtx.net/api/v1/servers -H "Authorization: Bearer $SIMTX_TOKEN"

Response

200 OK:

{
  "servers": [
    {
      "serverId": "argon",
      "displayName": "Argon",
      "host": "argon.simtx.net",
      "port": 5556,
      "description": "Main public server"
    }
  ]
}

Field	Type	Description
serverId	string	Stable identifier. Used when requesting a game ticket.
displayName	string	Name to show to users.
host	string	DNS name to connect to. Also the name to verify the server's TLS certificate against.
port	integer	TCP port of the game protocol.
description	string	Free text set by the operator. May be empty.

Entries are sorted by display name, then by server ID.

Semantics

• A server appears only while it is enabled and holds a live registration lease with the account service. The lease lasts 60 seconds and running servers keep renewing it, so a server that stops renewing it disappears from the list within about a minute.
• An empty servers array means that no server is online. It is not an error.
• Always connect to the host and port from the directory. The default port of the server software is 5100, but the public deployment currently listens on 5556, and operators may change it at any time.
• The directory may list several servers. Each is a separate simulated world; stations on one server cannot hear stations on another.

Receiving without an account

The directory requires a credential, but receiving does not. A receive-only client without an account can let the user enter a host and port, or ship with the public address as a default (argon.simtx.net:5556 at the time of writing) and treat it as configuration rather than a constant.

Errors

HTTP	code	Meaning
401	credential_missing	No bearer credential was sent.
401	credential_invalid	The credential is invalid or expired.
429	rate_limited	Too many requests this minute.