Editing SimTX API v24/Public endpoints

{{SimTX API v24 navigation}}
The [[SimTX API v24/Account service|account service]] exposes a handful of '''public endpoints''' that need no credential. They serve service status, public profiles, transmitter 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 v24/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 v24/Server directory|server directory]] for that. Not rate limited.

== 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 official SimTX Transmitter, 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). The official transmitter uses it for update checks.

<syntaxhighlight lang="properties">
version=0.3.7
url=/downloads/simtx-transmitter-0.3.7.jar
sha256=8632bc25e1271146c8638c2780e4a6bdb40379d0dd7cae8f0631f8e16b5da69b
notes=WFM now accepts baseband directly. · Added rate selection up to 384 kHz.
</syntaxhighlight>

The notes of the release are joined with <code> · </code> on a single line. 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. The SimTX website's network test uses them.

=== 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 v24 navbox}}
[[Category:SimTX API v24]]
[[Category:SimTX API v24 account service]]