SimTX API/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?include=features' -H "Authorization: Bearer $SIMTX_TOKEN"

Parameter	Description
include	Optional, comma-separated extras. features adds a features array to each entry.

Response

200 OK:

{
  "servers": [
    {
      "serverId": "argon",
      "displayName": "Argon",
      "host": "argon.simtx.net",
      "port": 5556,
      "description": "Main public server",
      "features": ["stations.v1", "pointing", "ephemeris", "passes", "kinematics"]
    }
  ]
}

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.
features	array of string	Only with include=features. The features that every live node of the server advertises. Ignore names you do not know.

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; sessions on one server cannot hear sessions on another. Persistent stations belong to the account, not to a server, and can be used on any server that supports them.
• A server needs the feature stations.v1 before the account service mints a station-bound ticket for it. The same list is in the game server's ServerHello after connecting.

Receiving without an account

The directory requires a credential, but receiving does not. An ad-hoc 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.