Editing SimTX API v24

{{SimTX API v24 navigation}}
The '''SimTX API''' is the set of public interfaces that third-party software uses to work with SimTX. With it, a program can receive the simulated radio spectrum as raw IQ samples, put its own transmitter on the air, read the list of stations, request coverage and weather maps, and publish packages to the extension catalog, all without the official SimTX Transmitter application.

The API has two parts:
* The '''[[SimTX API v24/Account service|account service]]''', an HTTPS JSON API at <code>auth.simtx.net</code>. It signs users in, lists game servers and issues single-use game tickets.
* The '''game protocol''', a binary protocol over TLS spoken directly with a game server. Receiving, transmitting and control traffic all use it. The current version is '''24'''.

This reference documents both as they are deployed. It does not cover the protocol that SimTX servers use among themselves, the propagation model, or administrative endpoints.

== How the pieces fit ==
<syntaxhighlight lang="text">
                 HTTPS + JSON                                   TLS + binary (v24)
  client ───────────────────────▶ auth.simtx.net      client ───────────────────────▶ game server
    1. device login       → credentials                  4. Handshake (role + ticket)
    2. GET  /api/v1/servers → host and port              5. session request
    3. POST /api/v1/game-tickets → one-shot ticket       6. IQ in, samples out, or control traffic
</syntaxhighlight>

* '''Receiving needs no account.''' The receiver, timestamped receiver and control roles accept anonymous connections. Such a client skips steps 1 to 3 and needs only a host and port.
* '''Transmitting needs an account''' with the <code>game.transmit</code> [[SimTX API v24/Permissions|permission]], and a fresh [[SimTX API v24/Game tickets|game ticket]] for every connection.
* '''One TCP connection is one session.''' A client that wants two receivers, or a receiver and a transmitter, opens two connections.

== Where to start ==
{| class="wikitable"
! If you want to… !! Read
|-
| See something working in five minutes || [[SimTX API v24/Quick start]]
|-
| Receive IQ from SimTX in your own SDR software || [[SimTX API v24/Connection and handshake]], then [[SimTX API v24/Receiver session]]
|-
| Transmit from your own software || [[SimTX API v24/Device login]], [[SimTX API v24/Game tickets]], then [[SimTX API v24/Transmitter session]]
|-
| Show a station list or map || [[SimTX API v24/Control session]]
|-
| Publish extensions from a script || [[SimTX API v24/Extension catalog protocol]]
|-
| Look up one packet || [[SimTX API v24/Packet list]]
|-
| Understand why the server hung up || [[SimTX API v24/Limits and errors]]
|}

== Reference pages ==
=== Account service ===
* [[SimTX API v24/Account service]]: base URL, authentication, credential formats, errors and rate limits.
* [[SimTX API v24/Device login]]: signing a user in from a desktop or command-line program.
* [[SimTX API v24/Server directory]]: discovering game servers.
* [[SimTX API v24/Game tickets]]: exchanging a credential for a one-shot game server ticket.
* [[SimTX API v24/Permissions]]: permission identifiers and numeric capabilities.
* [[SimTX API v24/Public endpoints]]: status, profiles, releases and network test.

=== Game protocol ===
* [[SimTX API v24/Data types]]: byte order, string encodings and shared structures.
* [[SimTX API v24/Connection and handshake]]: TLS, the handshake, roles and handshake results.
* [[SimTX API v24/Receiver session]]: requesting a receiver and decoding IQ.
* [[SimTX API v24/Transmitter session]]: admission, streaming samples, live updates and telemetry.
* [[SimTX API v24/Control session]]: station list, banners, health, coverage and weather maps, monitoring.
* [[SimTX API v24/Extension catalog protocol]]: listing, fetching, uploading and deleting catalog entries.
* [[SimTX API v24/Moderation session]]: moderator tools. Not usable without moderator permission.
* [[SimTX API v24/Limits and errors]]: session limits, timeouts, how failures are reported, reconnection.
* [[SimTX API v24/Packet list]]: every packet ID in both directions.

== Design notes ==
A few properties of the protocol are worth knowing before writing any code, because they explain most of its sharp edges:

* '''No length prefixes.''' Packets are an ID byte followed by a body whose layout the reader must already know. Reading one field too few or too many silently misaligns everything after it. Write the decoder carefully, and test it against a real server early.
* '''Silence is an answer.''' Several kinds of failure, especially invalid receiver requests and limit rejections, are reported by closing the connection without a message. When the socket closes right after a request, the request was probably invalid or over a limit. [[SimTX API v24/Limits and errors]] lists the cases.
* '''Exact version match.''' Server and client must both speak version 24. There is no negotiation and no backwards compatibility. A server that moves to a new version rejects old clients with a clear [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]] rather than misbehaving.
* '''Real time.''' Receivers get samples at the rate of the simulation, and transmitters must send samples at the rate they declared. Neither side waits for the other. A client that falls behind loses data.
* '''Physics, not a jukebox.''' The IQ a receiver gets is what an antenna at that location would deliver: propagation, fading, noise and interference included. A station that cannot be heard is often simply out of range, or on the wrong side of the day–night terminator. See [[Propagation Basics]].

== Versioning ==
The game protocol version is a single integer sent in the handshake. Any incompatible change increments it. Within a version, the TLV-encoded [[SimTX API v24/Packets/TransmitterSessionRequest|transmitter request]] may gain new optional fields, which older clients simply do not send.

The account service API is versioned in its path (<code>/api/v1/</code>). New response fields may be added without a version change; clients must ignore fields they do not recognise.

== Terms of use ==
SimTX is a shared simulation with other people listening. Software built on this API is subject to the same rules as the official application. Keep request rates within the documented limits, identify your software honestly in <code>clientName</code> during [[SimTX API v24/Device login|device login]], and do not use the API to disrupt other users.

{{SimTX API v24 navbox}}
[[Category:SimTX API v24]]