SimTX API v24/Server directory - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:27:21Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:27, 24 October 2026
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 ==		== Request ==
Line 31:		Line 31:
	! Field !! Type !! Description		! 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.		\| <code>displayName</code> \|\| string \|\| Name to show to users.
Line 51:		Line 51:

	== Receiving without an account ==		== 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 ==		== 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]]

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

← Older revision	Revision as of 16:20, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:51:02Z

SimTX API documentation

New page

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

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

<syntaxhighlight lang="json">
{
"servers": [
{
"serverId": "argon",
"displayName": "Argon",
"host": "argon.simtx.net",
"port": 5556,
"description": "Main public server"
}
]
}
</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.
|}

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; stations on one server cannot hear stations on another.

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

== 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]]