Editing SimTX API/Public endpoints

{{SimTX API navigation}}
The [[SimTX API/Account service|account service]] exposes a handful of '''public endpoints''' that need no credential. They serve service status, the public satellite list, public profiles, client releases and a simple network test. All are on <code><nowiki>https://auth.simtx.net</nowiki></code>; rate limits are listed on the [[SimTX API/Account service#Rate limits|account service]] page.

== Service status ==
<code>GET /api/v1/status</code>

<syntaxhighlight lang="json">
{ "status": "operational" }
</syntaxhighlight>

The response indicates only that the account service process is up and answering. It says nothing about game servers; use the [[SimTX API/Server directory|server directory]] for that. Not rate limited.

== Public satellites ==
<code>GET /api/v1/satellites</code>

Lists every PUBLIC satellite of every account that is <code>ACTIVE</code> or <code>DEORBITING</code> (not yet reentered). No authentication. Rate limit: 120 per minute.

<syntaxhighlight lang="json">
{
  "satellites": [
    {
      "stationId": "99999999-8888-4777-8666-555555555555",
      "revision": 3,
      "catalogSeq": 412,
      "state": "ACTIVE",
      "name": "SimSat-1",
      "callsign": "SSAT1",
      "ownerHandle": "n0call",
      "visibility": "PUBLIC",
      "orbit": {
        "model": "simtx-j2-v1", "epoch": "2026-10-20T12:00:00Z",
        "semiMajorAxisKm": 6921.0, "eccentricity": 0.001, "inclinationDeg": 97.6,
        "raanDeg": 120.0, "argumentOfPerigeeDeg": 90.0, "meanAnomalyDeg": 10.0
      },
      "attitude": { "mode": "NADIR", "yawDeg": 0.0 },
      "launchedAt": "2026-10-20T12:00:00Z"
    }
  ]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>stationId</code> || string (UUID) || The satellite's station id, as used in station lists, tickets and ephemeris requests.
|-
| <code>revision</code> || integer || Station revision.
|-
| <code>catalogSeq</code> || integer || Global sequence number, increased on every change to any satellite.
|-
| <code>state</code> || string || <code>ACTIVE</code> or <code>DEORBITING</code>.
|-
| <code>name</code>, <code>callsign</code>, <code>ownerHandle</code> || string || As on the station.
|-
| <code>visibility</code> || string || Always <code>PUBLIC</code> here.
|-
| <code>orbit</code>, <code>attitude</code> || object || As on [[SimTX API/Station endpoints#Orbit and attitude|Station endpoints]]. After a deorbit burn, the post-burn elements.
|-
| <code>launchedAt</code> || string || Launch time; also the epoch of the original elements.
|-
| <code>deorbit</code> || object || Set once the deorbit burn has fired: <code>burnAt</code>, <code>reentryAt</code>, <code>reentryLocation</code>, <code>deltaVMps</code>, <code>orbit</code>. Stop drawing the satellite at <code>reentryAt</code>.
|}

The list is served from a snapshot at most 5 seconds old, replaced as soon as any satellite changes. Responses carry an <code>ETag</code> and <code>Cache-Control: no-cache</code>; send <code>If-None-Match</code> to get <code>304 Not Modified</code> when nothing changed. Propagate the elements with the [[SimTX API/Satellites#Orbit model|orbit model]] to draw the satellites.

== Public profiles ==
Every active account has a public profile consisting of its handle, display name, join date, public badges and visible awards. Nothing else about an account is public.

=== Profile search ===
<code>GET /api/v1/profiles?q=</code>''text''

{| class="wikitable"
! Parameter !! Description
|-
| <code>q</code> || Case-insensitive substring matched against handles and display names. Optional; an empty query lists accounts alphabetically.
|}

Returns at most 24 profiles. An exact handle match is listed first, then the rest ordered by handle.

<syntaxhighlight lang="json">
{
  "profiles": [
    {
      "handle": "n0call",
      "displayName": "Example Operator",
      "joinedAt": "2026-08-20T09:12:44.100000Z",
      "badges": [
        { "roleKey": "SUPPORTER", "label": "Supporter", "color": "#e0b04c" }
      ]
    }
  ]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>handle</code> || string || Unique handle. Users may change it, at most once every 30 days.
|-
| <code>displayName</code> || string || Free-form display name.
|-
| <code>joinedAt</code> || string || Account creation time.
|-
| <code>badges</code> || array || Public role badges, sorted by label.
|-
| <code>badges[].roleKey</code> || string || Stable role identifier, for example <code>SUPPORTER</code> or <code>MODERATOR</code>.
|-
| <code>badges[].label</code> || string || Text to display.
|-
| <code>badges[].color</code> || string || CSS colour for the badge, usually <code>#rrggbb</code>.
|}

=== Single profile ===
<code>GET /api/v1/profiles/{handle}</code>

Returns the same fields as a search result plus <code>awards</code>. Unknown handles return <code>404 profile_not_found</code>.

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>awards[].awardId</code> || string (UUID) || Award definition.
|-
| <code>awards[].accountAwardId</code> || string (UUID) || This particular grant.
|-
| <code>awards[].slug</code> || string || Stable short identifier of the award.
|-
| <code>awards[].name</code> || string || Display name.
|-
| <code>awards[].description</code> || string || Description.
|-
| <code>awards[].iconUrl</code> || string || Icon image URL. May be empty.
|-
| <code>awards[].grantedAt</code> || string || When the award was granted.
|-
| <code>awards[].visible</code> || boolean || Whether the user shows it on their profile. Only visible awards are returned here.
|-
| <code>awards[].displayOrder</code> || integer || Order chosen by the user; lower first.
|-
| <code>awards[].revokedAt</code> || string or null || Always null for awards returned here.
|}

== Releases ==
<code>GET /api/v1/releases</code>

Lists published releases of the SimTX Transmitter application, newest first.

<syntaxhighlight lang="json">
{
  "releases": [
    {
      "releaseId": "7edca7c6-97ca-4291-9691-3f0a5cd41a20",
      "version": "0.3.7",
      "title": "SimTX 0.3.7",
      "notes": ["WFM now accepts baseband directly.", "Added rate selection up to 384 kHz."],
      "downloadUrl": "/downloads/simtx-transmitter-0.3.7.jar",
      "artifactFilename": "simtx-transmitter-0.3.7.jar",
      "artifactSize": 8087129,
      "artifactSha256": "8632bc25e1271146c8638c2780e4a6bdb40379d0dd7cae8f0631f8e16b5da69b",
      "published": true,
      "createdAt": "2026-09-14T19:37:41.639246Z",
      "updatedAt": "2026-09-14T19:38:53.435832Z",
      "publishedAt": "2026-09-14T19:37:41.639246Z"
    }
  ]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>version</code> || string || Version number.
|-
| <code>title</code> || string || Release title.
|-
| <code>notes</code> || array of string || Change notes, one entry per item.
|-
| <code>downloadUrl</code> || string or null || Download location. A value starting with <code>/</code> is relative to <code><nowiki>https://auth.simtx.net</nowiki></code>; otherwise it is an absolute URL.
|-
| <code>artifactFilename</code>, <code>artifactSize</code>, <code>artifactSha256</code> || string, integer, string || File name, size in bytes and lowercase hex SHA-256 of the download. Verify the hash after downloading.
|-
| <code>published</code> || boolean || Always true here.
|-
| <code>createdAt</code>, <code>updatedAt</code>, <code>publishedAt</code> || string || Timestamps.
|}

=== Release downloads ===
<code>GET /downloads/{filename}</code> returns the stored file with <code>Content-Disposition: attachment</code>, an <code>ETag</code> equal to the quoted SHA-256, and <code>Cache-Control: public, max-age=300</code>. Unknown files return <code>404 release_artifact_not_found</code>.

=== Update manifest ===
<code>GET /downloads/transmitter-update.properties</code> returns the newest downloadable release as a Java properties file (<code>text/plain; charset=utf-8</code>, cached for 60 seconds).

<syntaxhighlight lang="properties">
version=0.3.7
url=/downloads/simtx-transmitter-0.3.7.jar
sha256=8632bc25e1271146c8638c2780e4a6bdb40379d0dd7cae8f0631f8e16b5da69b
notes=WFM now accepts baseband directly.
</syntaxhighlight>

When a release has several notes, they are joined on a single line, separated by a space, the character U+00B7 and a space. Returns <code>404 release_manifest_unavailable</code> when no release has a download.

== Network test ==
Two endpoints let a client estimate latency and upload bandwidth to SimTX infrastructure.

=== Latency probe ===
<code>GET /api/v1/network-test/ping</code>

<syntaxhighlight lang="json">
{ "serverTimeMillis": 1793016000000 }
</syntaxhighlight>

<code>serverTimeMillis</code> is the server's clock in Unix milliseconds. Measure the round-trip time on the client side. Rate limit: 60 per minute.

=== Upload probe ===
<code>POST /api/v1/network-test/upload</code> with <code>Content-Type: application/octet-stream</code> and a body of 1 byte to 1 MiB (1,048,576 bytes). The <code>Content-Length</code> header is required.

<syntaxhighlight lang="json">
{ "receivedBytes": 1048576, "serverReadMillis": 412.7 }
</syntaxhighlight>

{| class="wikitable"
! Field !! Description
|-
| <code>receivedBytes</code> || Number of body bytes read.
|-
| <code>serverReadMillis</code> || Time the server spent reading the body, in milliseconds.
|}

Errors: <code>415 network_test_content_type</code> for any other content type, <code>413 network_test_chunk_size</code> for an empty, missing-length or oversized body. Rate limit: 144 per minute.

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