SimTX API v24/Server directory: Difference between revisions

Latest revision as of 16:27, 24 October 2026

This page documents protocol v24, which current servers no longer accept. See SimTX API for v25.

v24 overviewQuick startAccount serviceHandshakeAll packetsData typesLimits and errorsCurrent reference (v25)

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 -H "Authorization: Bearer $SIMTX_TOKEN"

Response[edit | edit source]

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

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

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[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 v24 reference (protocol v24, archived)
Start	OverviewQuick startData typesLimits and errorsPacket list
Account service	OverviewDevice loginServer directoryGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeReceiver sessionTransmitter sessionControl sessionCatalogModeration
Handshake	HandshakeHandshakeResult
Receiver	ReceiverSessionRequestReceiverRetuneForwardedClientAddressIqStreamDescriptorIqBlockTimedIqBlock
Transmitter	TransmitterSessionRequestSampleBlockTxModeInfoTxUpdateTxQueueTxAcceptTxRejectTxKickTxTelemetryTxUpdateAck
Control	ControlAckBannerListStationsStationListServerHealthRequestServerHealthReportCoverageMapRequestCoverageMapResponseWeatherMapRequestWeatherMapResponseStartMonitorStopMonitorMonitorBlockMonitorEnd
Catalog	CatalogListRequestCatalogListCatalogFetchCatalogEntryCatalogUploadCatalogUploadResultCatalogDeleteCatalogDeleteResult
Moderation	KickRequestKickResultIpModerationRequestIpModerationResultBroadcastBannerModerationErrorStationImpactList
Current	Protocol v25 reference

@@ Line 1: / Line 1: @@
-{{SimTX API navigation}}
+{{SimTX API v24 navigation}}
-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 [[SimTX API/Connection and handshake|game connection]].
+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 [[SimTX API v24/Connection and handshake|game connection]].
 == Request ==
@@ Line 31: / Line 31: @@
 ! Field !! Type !! Description
 |-
-| <code>serverId</code> || string || Stable identifier. Used when requesting a [[SimTX API/Game tickets|game ticket]].
+| <code>serverId</code> || string || Stable identifier. Used when requesting a [[SimTX API v24/Game tickets|game ticket]].
 |-
 | <code>displayName</code> || string || Name to show to users.
@@ Line 51: / Line 51: @@
 == Receiving without an account ==
-The directory requires a credential, but [[SimTX API/Receiver session|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 (<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 v24/Receiver session|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 (<code>argon.simtx.net:5556</code> at the time of writing) and treat it as configuration rather than a constant.
 == Errors ==
@@ Line 64: / Line 64: @@
 |}
-{{SimTX API navbox}}
+{{SimTX API v24 navbox}}
-[[Category:SimTX API]]
+[[Category:SimTX API v24]]
-[[Category:SimTX API account service]]
+[[Category:SimTX API v24 account service]]