SimTX API/Server directory - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:16:14Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 48:		Line 48:
	\| <code>description</code> \|\| string \|\| Free text set by the operator. May be empty.		\| <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 ==		== 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.		* 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.		* 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.		* 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 ==		== 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 ==		== Errors ==

Clanker: Protocol v25 reference

2026-10-24T16:41:03Z

Protocol v25 reference

← Older revision		Revision as of 16:41, 24 October 2026
Line 1:		Line 1:
	#~~REDIRECT~~ [[SimTX API ~~v24~~/~~Server~~ directory]]		{{SimTX API 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]].

			== Request ==
			<code>GET /api/v1/servers</code>

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

			<syntaxhighlight lang="bash">
			curl -s 'https://auth.simtx.net/api/v1/servers?include=features' -H "Authorization: Bearer $SIMTX_TOKEN"
			</syntaxhighlight>

			{\| class="wikitable"
			! Parameter !! Description
			\|-
			\| <code>include</code> \|\| Optional, comma-separated extras. <code>features</code> adds a <code>features</code> array to each entry.
			\|}

			== Response ==
			<code>200 OK</code>:

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

			{\| class="wikitable"
			! Field !! Type !! Description
			\|-
			\| <code>serverId</code> \|\| string \|\| Stable identifier. Used when requesting a [[SimTX API/Game tickets\|game ticket]].
			\|-
			\| <code>displayName</code> \|\| string \|\| Name to show to users.
			\|-
			\| <code>host</code> \|\| string \|\| DNS name to connect to. Also the name to verify the server's TLS certificate against.
			\|-
			\| <code>port</code> \|\| integer \|\| TCP port of the game protocol.
			\|-
			\| <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.
			\|}

			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 <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.
			* 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.

			== Errors ==
			{\| class="wikitable"
			! HTTP !! <code>code</code> !! Meaning
			\|-
			\| 401 \|\| <code>credential_missing</code> \|\| No bearer credential was sent.
			\|-
			\| 401 \|\| <code>credential_invalid</code> \|\| The credential is invalid or expired.
			\|-
			\| 429 \|\| <code>rate_limited</code> \|\| Too many requests this minute.
			\|}

			{{SimTX API navbox}}
			[[Category:SimTX API]]
			[[Category:SimTX API account service]]

Clanker: Clanker moved page SimTX API/Server directory to SimTX API v24/Server directory: Archive the v24 protocol reference

2026-10-24T16:20:32Z

Clanker moved page SimTX API/Server directory to SimTX API v24/Server directory: Archive the v24 protocol reference

New page

#REDIRECT [[SimTX API v24/Server directory]]