SimTX API/Server directory: Difference between revisions

Latest revision as of 17:16, 24 October 2026

API overviewQuick startHandshakeFramingAll messagesData typesStationsAccount serviceLimits and errorsv24 reference

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[edit | edit source]

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[edit | edit source]

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 the server advertises. Ignore names you do not know.

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

Semantics[edit | edit source]

A server that goes offline 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. argon.simtx.net listens on 5556.
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[edit | edit source]

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 argon.simtx.net:5556 as a configurable default.

Errors[edit | edit source]

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.

SimTX API reference (protocol v25)
Start	OverviewQuick startFramingData typesPacket listSchemaLimits and errorsCompatibility and versioning
Account service	OverviewDevice loginServer directoryStation endpointsGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeSession statusReceiver sessionTransmitter sessionControl sessionCatalogModeration
Stations	StationsSatellitesTracking and pointing
Connection	ClientHelloPingServerHelloPongErrorBanner
Session	AntennaPointingUpdateSessionStatus
Receiver	ForwardedClientAddressReceiverStartReceiverRetuneIqStreamDescriptorIqBlock
Transmitter	TransmitterStartSampleBlockTxUpdateTxModeInfoTxQueueTxAcceptTxTelemetryTxUpdateAck
Control	ListStationsStartMonitorStopMonitorWeatherMapRequestServerHealthRequestCoverageMapRequestEphemerisRequestPassPredictionRequestStationListMonitorBlockMonitorEndWeatherMapResponseServerHealthReportCoverageMapResponseEphemerisResponsePassPredictionResponseMonitorAck
Catalog	CatalogListRequestCatalogFetchCatalogUploadCatalogDeleteCatalogListCatalogEntryCatalogUploadResultCatalogDeleteResult
Moderation	KickRequestIpModerationRequestBroadcastBannerKickResultIpModerationResultStationImpactList
Archive	Protocol v24 reference

@@ Line 48: / Line 48: @@
 | <code>description</code> || string || Free text set by the operator. May be empty.
 |-
-| <code>features</code> || array of string || Only with <code>include=features</code>. The [[SimTX API/Compatibility and versioning#Feature registry|features]] that every live node of the server advertises. Ignore names you do not know.
+| <code>features</code> || array of string || Only with <code>include=features</code>. The [[SimTX API/Compatibility and versioning#Feature registry|features]] the server advertises. Ignore names you do not know.
 |}
@@ Line 54: / Line 54: @@
 == 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.
+* A server that goes offline disappears from the list within about a minute.
 * An empty <code>servers</code> array means that no server is online. It is not an error.
-* Always connect to the <code>host</code> and <code>port</code> 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.
+* Always connect to the <code>host</code> and <code>port</code> from the directory. <code>argon.simtx.net</code> listens on '''5556'''.
 * The directory may list several servers. Each is a separate simulated world; sessions on one server cannot hear sessions on another. Persistent [[SimTX API/Stations|stations]] belong to the account, not to a server, and can be used on any server that supports them.
 * A server needs the feature <code>stations.v1</code> before the account service mints a station-bound [[SimTX API/Game tickets|ticket]] for it. The same list is in the game server's [[SimTX API/Packets/ServerHello|ServerHello]] after connecting.
 == Receiving without an account ==
-The directory requires a credential, but [[SimTX API/Receiver session|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 (<code>argon.simtx.net:5556</code> at the time of writing) and treat it as configuration rather than a constant.
+The directory requires a credential, but [[SimTX API/Receiver session|receiving]] does not. An ad-hoc receive-only client without an account can let the user enter a host and port, or ship with <code>argon.simtx.net:5556</code> as a configurable default.
 == Errors ==