Editing SimTX API

{{SimTX API 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, manage persistent stations and launch satellites, read the list of stations, request coverage and weather maps, satellite ephemerides and pass predictions, and publish packages to the extension catalog, all without the official SimTX applications.

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

This reference covers what a client sends and receives. The version 24 reference is at [[SimTX API v24]].

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

* '''Receiving needs no account.''' An ad-hoc receiver, which brings its own callsign, position and antenna, and the control role accept anonymous connections. Such a client skips steps 1 to 4 and needs only a host and port.
* '''Transmitting needs an account and a station.''' A transmitter is bound to one of the account's persistent [[SimTX API/Stations|stations]]. It needs the <code>game.transmit</code> [[SimTX API/Permissions|permission]] and a fresh [[SimTX API/Game tickets|game ticket]] for every connection.
* '''Station-bound reception''' works on the account's own stations and on any PUBLIC station of another account, including [[SimTX API/Satellites|satellites]].
* '''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
|-
| Receive IQ with a minimal script || [[SimTX API/Quick start]]
|-
| Receive IQ in your own SDR software || [[SimTX API/Connection and handshake]], [[SimTX API/Framing]], then [[SimTX API/Receiver session]]
|-
| Transmit from your own software || [[SimTX API/Device login]], [[SimTX API/Stations]], [[SimTX API/Game tickets]], then [[SimTX API/Transmitter session]]
|-
| Create stations or launch a satellite || [[SimTX API/Station endpoints]], [[SimTX API/Satellites]]
|-
| Track a satellite and correct Doppler || [[SimTX API/Tracking and pointing]]
|-
| Show a station list or map || [[SimTX API/Control session]]
|-
| Publish extensions from a script || [[SimTX API/Extension catalog protocol]]
|-
| Look up one message || [[SimTX API/Packet list]]
|-
| Understand why a session ended || [[SimTX API/Session status]], [[SimTX API/Limits and errors]]
|}

== Reference pages ==
=== Account service ===
* [[SimTX API/Account service]]: base URL, authentication, credential formats, errors and rate limits.
* [[SimTX API/Device login]]: signing a user in from a desktop or command-line program.
* [[SimTX API/Server directory]]: discovering game servers and their features.
* [[SimTX API/Station endpoints]]: creating and editing stations, launching and deorbiting satellites.
* [[SimTX API/Game tickets]]: exchanging a credential for a one-shot game server ticket, optionally bound to a station.
* [[SimTX API/Permissions]]: scopes, permission identifiers and numeric capabilities.
* [[SimTX API/Public endpoints]]: status, public satellites, profiles, releases and network test.

=== Game protocol ===
* [[SimTX API/Connection and handshake]]: TLS, the preface, the hello, roles and hello results.
* [[SimTX API/Framing]]: length-delimited frames, size limits and skipping unknown frames.
* [[SimTX API/Data types]]: protobuf types, conventions and shared messages.
* [[SimTX API/Session status]]: how receiver and transmitter sessions are bound, updated, refused and ended.
* [[SimTX API/Receiver session]]: requesting a receiver and decoding IQ.
* [[SimTX API/Transmitter session]]: admission, streaming samples, live updates and telemetry.
* [[SimTX API/Control session]]: station list, banners, health, coverage and weather maps, ephemerides, passes, monitoring.
* [[SimTX API/Extension catalog protocol]]: listing, fetching, uploading and deleting catalog entries.
* [[SimTX API/Moderation session]]: moderator tools. Not usable without moderator permission.
* [[SimTX API/Limits and errors]]: the error model, session limits, rate limits and timeouts.
* [[SimTX API/Compatibility and versioning]]: protocol revisions, the feature registry and what may change.
* [[SimTX API/Packet list]]: every frame member in both directions.
* [[SimTX API/Schema]]: the <code>.proto</code> files.

=== Stations and satellites ===
* [[SimTX API/Stations]]: persistent stations, station-bound and ad-hoc sessions, what the station dictates.
* [[SimTX API/Satellites]]: user-launched satellites, the orbit model, ephemerides, passes and deorbiting.
* [[SimTX API/Tracking and pointing]]: steerable antennas, rotators and Doppler correction.

== Design notes ==
* '''Protobuf frames.''' Every message is a protobuf message. On the wire each one is a varint length followed by a <code>ClientFrame</code> or <code>ServerFrame</code>, a message with a single <code>oneof</code>. The recommended approach is to generate bindings from the [[SimTX API/Schema|.proto files]] with <code>protoc</code>. A hand-written codec needs only varints, 32- and 64-bit little-endian values and length-delimited fields; [[SimTX API/Quick start]] shows one in a few dozen lines of Python.
* '''Unknown is not an error.''' A frame whose <code>oneof</code> member a reader does not know, and a field it does not know, are skipped. See [[SimTX API/Compatibility and versioning]].
* '''Rejections are never silent.''' A refused hello gets a [[SimTX API/Packets/ServerHello|ServerHello]] with a status, a refused or ended session a [[SimTX API/Packets/SessionStatus|SessionStatus]] with an error code and a reason, and a failed request an [[SimTX API/Packets/Error|Error]] with its <code>request_id</code>.
* '''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.
* '''Simulated reception.''' The IQ a receiver gets includes the propagation, fading, Doppler shift, noise and interference at its location and antenna. See [[Propagation Basics]].

== Versioning ==
The game protocol version is the integer in the 8-byte preface; the current version is 25. Both hellos carry a '''protocol revision''', and optional server capabilities appear in the '''feature registry'''. See [[SimTX API/Compatibility and versioning]].

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 applications. Keep request rates within the documented limits, identify your software honestly in <code>clientName</code> during [[SimTX API/Device login|device login]] and in <code>ClientHello.client_name</code>, and do not use the API to disrupt other users.

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