Editing SimTX API/Station endpoints

{{SimTX API navigation}}
The '''station endpoints''' of the [[SimTX API/Account service|account service]] create, read, edit and delete an account's persistent [[SimTX API/Stations|stations]], launch [[SimTX API/Satellites|satellites]] and deorbit them. A station belongs to the account, not to a game server; game sessions attach to it with a station-bound [[SimTX API/Game tickets|game ticket]].

All endpoints take a bearer credential (an access credential or a personal credential) on <code><nowiki>https://auth.simtx.net</nowiki></code>. Service credentials are refused with <code>403 account_credential_required</code>.

== Endpoints ==
{| class="wikitable"
! Method and path !! Scope !! Result
|-
| <code>GET /api/v1/stations</code> || Any || <code>200 {"stations": [Station]}</code>: your stations
|-
| <code>POST /api/v1/stations</code> || <code>station.manage</code> || <code>201 Station</code>: create a ground station
|-
| <code>GET /api/v1/stations/{id}</code> || Any || <code>200 Station</code>
|-
| <code>PATCH /api/v1/stations/{id}</code> || <code>station.manage</code> || <code>200 Station</code>
|-
| <code>DELETE /api/v1/stations/{id}</code> || <code>station.manage</code> || <code>204</code>
|-
| <code>POST /api/v1/stations/{id}/antennas</code> || <code>station.manage</code> || <code>201 Station</code> (ground stations only)
|-
| <code>PATCH</code>, <code>DELETE /api/v1/stations/{id}/antennas/{antennaId}</code> || <code>station.manage</code> || <code>200 Station</code>
|-
| <code>POST /api/v1/stations/{id}/rigs</code> || <code>station.manage</code> || <code>201 Station</code> (ground stations only)
|-
| <code>PATCH</code>, <code>DELETE /api/v1/stations/{id}/rigs/{rigId}</code> || <code>station.manage</code> || <code>200 Station</code>
|-
| <code>POST /api/v1/satellites</code> || <code>station.manage</code> || <code>201 Station</code>: launch a satellite
|-
| <code>POST /api/v1/stations/{id}/deorbit/preview</code> || Any || <code>200 Deorbit</code>: what a burn now would do
|-
| <code>POST /api/v1/stations/{id}/deorbit</code> || <code>station.manage</code> || <code>200 Station</code>: fire the deorbit burn
|-
| <code>GET /api/v1/satellites</code> || None (public) || <code>200 {"satellites": [SatelliteCatalogEntry]}</code>; see [[SimTX API/Public endpoints#Public satellites|Public endpoints]]
|}

"Any" means any account credential, without a particular scope. A write with a credential whose scope lacks <code>station.manage</code> is refused with <code>403 scope_required</code> and <code>fieldErrors.scope = "station.manage"</code>; sign the user in again with the wider scope. An account without the permission gets <code>403 permission_denied</code>. Rate limits: 240 reads and 120 writes per minute per IP address.

== The Station object ==
<syntaxhighlight lang="json">
{
  "stationId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "ownerAccountId": "0f8e2c4a-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
  "ownerHandle": "n0call",
  "kind": "GROUND",
  "state": "ACTIVE",
  "name": "Home",
  "callsign": "N0CALL",
  "visibility": "UNLISTED",
  "revision": 3,
  "limits": { "maxSessions": 16, "maxTransmitters": 4, "maxReceivers": 16 },
  "location": { "latitudeDeg": 47.4979, "longitudeDeg": 19.0402, "altitudeMeters": 120.0 },
  "antennas": [
    {
      "antennaId": "9b2c1e47-2f0a-4c55-8d1e-6a7b8c9d0e1f",
      "name": "40 m dipole", "ordinal": 0, "revision": 1,
      "type": "DIPOLE", "heightMeters": 10.0, "azimuthDeg": 90.0,
      "feedlineLossDb": 1.0, "wireLengthMeters": 0.0, "mount": "FIXED"
    }
  ],
  "rigs": [
    {
      "rigId": "c41d7a52-0e3b-4f6a-9c8d-1b2a3c4d5e6f",
      "name": "100 W transceiver", "revision": 1,
      "paMaxWatts": 100.0, "noiseFigureDb": 6.0,
      "tx": { "carrierLeakDb": 55.0, "oppositeSidebandSuppressionDb": 50.0 }
    }
  ],
  "createdAt": "2026-10-24T12:00:00Z",
  "updatedAt": "2026-10-24T12:30:00Z"
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>stationId</code> || string (UUID) || Never changes.
|-
| <code>ownerAccountId</code>, <code>ownerHandle</code> || string || The owning account.
|-
| <code>kind</code> || string || <code>GROUND</code> or <code>SATELLITE</code>.
|-
| <code>state</code> || string || <code>ACTIVE</code>, <code>DEORBITING</code> or <code>DEORBITED</code>. Ground stations are always <code>ACTIVE</code>.
|-
| <code>name</code>, <code>callsign</code> || string || 1 to 64 characters each.
|-
| <code>visibility</code> || string || <code>PUBLIC</code> or <code>UNLISTED</code>. See [[SimTX API/Stations#Visibility|Visibility]].
|-
| <code>revision</code> || integer || Increases with every edit of the station.
|-
| <code>limits</code> || object || <code>maxSessions</code>, <code>maxTransmitters</code>, <code>maxReceivers</code>, each 0 to 10,000, clamped to the owner's <code>game.station_sessions.N</code>.
|-
| <code>location</code> || object || Ground stations: <code>latitudeDeg</code> (−90 to 90), <code>longitudeDeg</code> (−180 to 180), <code>altitudeMeters</code> (−500 to 10,000).
|-
| <code>orbit</code>, <code>attitude</code> || object || Satellites. See [[#Orbit and attitude|Orbit and attitude]].
|-
| <code>deorbit</code> || object || Satellites whose deorbit burn has fired. See [[#Deorbiting|Deorbiting]].
|-
| <code>antennas</code> || array || 1 to 8 antennas (satellites: 1 to 4). See [[#Antennas and rigs|Antennas and rigs]].
|-
| <code>rigs</code> || array || 0 to 8 rigs.
|-
| <code>createdAt</code>, <code>updatedAt</code>, <code>launchedAt</code>, <code>deorbitedAt</code> || string || Timestamps; <code>launchedAt</code> and <code>deorbitedAt</code> for satellites.
|}

=== Antennas and rigs ===
An '''antenna''' has <code>antennaId</code>, <code>name</code> (at most 64 characters), <code>ordinal</code> (its position; the first antenna is the default for tickets), <code>revision</code>, and the fields of the game protocol's [[SimTX API/Data types#AntennaConfig|AntennaConfig]] in camelCase:

{| class="wikitable"
! Field !! Description
|-
| <code>type</code> || An [[SimTX API/Data types#Antenna types|antenna type]] name.
|-
| <code>heightMeters</code> || ≥ 0. Default 10 for ground stations, 0 for satellites.
|-
| <code>azimuthDeg</code> || −360 to 360.
|-
| <code>feedlineLossDb</code> || ≥ 0. Default 1 for ground stations, 0 for satellites.
|-
| <code>wireLengthMeters</code> || ≥ 0. 0 sizes the template for the operating frequency.
|-
| <code>necDeck</code> || Optional NEC-2 deck, at most 262,144 bytes; replaces the template. Satellite decks must not contain a <code>GN</code> card. Responses add <code>necDeckSha256</code>, the hex SHA-256 of the deck. Station lists carry only <code>necDeckSha256</code>; read the station for the deck text. A removed antenna, a deleted station and a reentered satellite keep no deck.
|-
| <code>mount</code> || <code>FIXED</code> (default), <code>AZ</code> or <code>AZEL</code>.
|-
| <code>pointing</code> || Steerable mounts only: <code>mode</code> (<code>FIXED</code> or <code>TRACK</code>), <code>azimuthDeg</code> (−360 to 360), <code>elevationDeg</code> (−90 to 90), <code>targetStationId</code> (required for <code>TRACK</code>), <code>azimuthRateDegPerSec</code> and <code>elevationRateDegPerSec</code> (0 to 360; 0 = default). A <code>FIXED</code> mount stores no pointing. See [[SimTX API/Tracking and pointing]].
|}

A '''rig''' is a saved radio profile: <code>rigId</code>, <code>name</code>, <code>revision</code>, <code>paMaxWatts</code> (0 to 10,000,000; default 100), <code>noiseFigureDb</code> (0 to 100; default 6), and <code>tx</code>, an object with the fifteen [[SimTX API/Data types#TxImperfections|transmitter imperfection]] values in camelCase (<code>finalDriveDb</code>, <code>paHeadroomDb</code>, <code>audioCompressionDb</code>, <code>paSoftness</code>, <code>paAmPmDeg</code>, <code>carrierLeakDb</code>, <code>oppositeSidebandSuppressionDb</code>, <code>frequencyOffsetHz</code>, <code>mainsHumDb</code>, <code>mainsHumHz</code>, <code>amModulationIndex</code>, <code>paSupplySagDb</code>, <code>txNoiseFloorDb</code>, <code>oscillatorPhaseNoiseDb</code>, <code>cwKeyRiseMs</code>). Values left out take the generic HF preset. Each value must lie in the range the game accepts (see [[SimTX API/Data types#TxImperfections|TxImperfections]]); other values are refused with <code>400 station_invalid</code>.

=== Orbit and attitude ===
<code>orbit</code> holds the mean elements of the [[SimTX API/Satellites#Orbit model|simtx-j2-v1]] model: <code>model</code> (<code>simtx-j2-v1</code>), <code>epoch</code> (read-only), <code>semiMajorAxisKm</code>, <code>eccentricity</code>, <code>inclinationDeg</code>, <code>raanDeg</code>, <code>argumentOfPerigeeDeg</code>, <code>meanAnomalyDeg</code>.

<code>attitude</code> has a <code>mode</code> of <code>NADIR</code>, <code>INERTIAL</code> or <code>SPIN</code> and the fields of that mode: <code>yawDeg</code>; <code>rightAscensionDeg</code>, <code>declinationDeg</code> (−90 to 90), <code>rollDeg</code>; or <code>spinAxis</code> (<code>NADIR</code>, <code>ORBIT_NORMAL</code>, <code>VELOCITY</code>), <code>spinRateRpm</code> (0 to 60), <code>spinPhaseDeg</code>. See [[SimTX API/Satellites#Attitude|Attitude]].

== Listing stations ==
<code>GET /api/v1/stations</code> returns the account's stations, ground and satellite, including deorbited satellites that have not been deleted.

<syntaxhighlight lang="bash">
curl -s https://auth.simtx.net/api/v1/stations -H "Authorization: Bearer $SIMTX_TOKEN"
</syntaxhighlight>

Antennas in the list carry <code>necDeckSha256</code> but no <code>necDeck</code>; <code>GET /api/v1/stations/{id}</code> returns the deck text.

== Creating a ground station ==
<code>POST /api/v1/stations</code>

<syntaxhighlight lang="json">
{
  "name": "Home",
  "callsign": "N0CALL",
  "visibility": "UNLISTED",
  "location": { "latitudeDeg": 47.4979, "longitudeDeg": 19.0402, "altitudeMeters": 120.0 },
  "antennas": [ { "name": "40 m dipole", "type": "DIPOLE", "heightMeters": 10.0, "azimuthDeg": 90.0 } ],
  "rigs": [ { "name": "100 W transceiver", "paMaxWatts": 100.0, "noiseFigureDb": 6.0 } ]
}
</syntaxhighlight>

<code>name</code>, <code>callsign</code>, <code>location</code> and at least one antenna are required. <code>visibility</code> defaults to <code>UNLISTED</code>, <code>limits</code> to 16 sessions, 4 transmitters and 16 receivers before clamping. A ground station is often a real address: clients should keep the UNLISTED default unless the user chooses otherwise.

== Reading, editing and deleting ==
* <code>GET /api/v1/stations/{id}</code> returns one station. Another account's station is <code>404 station_not_found</code>.
* <code>PATCH /api/v1/stations/{id}</code> takes any of <code>name</code>, <code>callsign</code>, <code>visibility</code>, <code>limits</code> and, for ground stations, <code>location</code>. Omitted fields keep their values. There is no cooldown on location changes.
* <code>DELETE /api/v1/stations/{id}</code> deletes a ground station, or a satellite that has reentered (<code>DEORBITED</code>). An active or deorbiting satellite is refused with <code>409 satellite_active</code>.

Every edit increases the station's <code>revision</code>. Sessions bound to the station either continue with the new values or end; see [[SimTX API/Stations#Edits while sessions run|Edits while sessions run]].

=== Antennas and rigs ===
Ground stations only; a launched satellite is sealed.
* <code>POST /api/v1/stations/{id}/antennas</code> adds an antenna (at most 8). <code>PATCH .../antennas/{antennaId}</code> changes one; omitted fields keep their values. <code>DELETE .../antennas/{antennaId}</code> removes one; the last antenna cannot be removed (<code>409 last_antenna</code>).
* <code>POST /api/v1/stations/{id}/rigs</code> adds a rig (at most 8). <code>PATCH .../rigs/{rigId}</code> changes one; a <code>tx</code> object replaces the stored imperfection values as a whole. <code>DELETE .../rigs/{rigId}</code> removes one.

Each returns the whole station.

== Launching a satellite ==
<code>POST /api/v1/satellites</code>

<syntaxhighlight lang="json">
{
  "name": "SimSat-1",
  "callsign": "SSAT1",
  "visibility": "PUBLIC",
  "orbit": {
    "model": "simtx-j2-v1",
    "semiMajorAxisKm": 6921.0, "eccentricity": 0.001, "inclinationDeg": 97.6,
    "raanDeg": 120.0, "argumentOfPerigeeDeg": 90.0, "meanAnomalyDeg": 10.0
  },
  "attitude": { "mode": "NADIR", "yawDeg": 0.0 },
  "antennas": [ { "name": "70 cm turnstile", "type": "TURNSTILE" } ],
  "rigs": [ { "name": "Beacon", "paMaxWatts": 2.0, "noiseFigureDb": 2.0 } ]
}
</syntaxhighlight>

* <code>name</code>, <code>callsign</code>, <code>orbit</code> and 1 to 4 antennas are required; up to 8 rigs.
* The orbit is sent without <code>epoch</code>. The account service sets the epoch to the launch instant and interprets the elements at that instant.
* The orbit must pass [[SimTX API/Satellites#Validation|validation]]: model <code>simtx-j2-v1</code>, perigee at least 200 km and apogee at most 40,000 km above the 6,371 km sphere, 0 ≤ ''e'' < 1, 0 ≤ ''i'' ≤ 180°, finite angles, spin rate 0 to 60 rpm.
* Satellite antennas are modelled in free space; their NEC decks must not contain a <code>GN</code> card.
* After launch the satellite is '''sealed''': only <code>name</code>, <code>callsign</code>, <code>visibility</code> and <code>limits</code> can change. Changes to the orbit, attitude, antennas or rigs are refused with <code>409 station_sealed</code>.

== Deorbiting ==
* <code>POST /api/v1/stations/{id}/deorbit/preview</code> returns the <code>Deorbit</code> object that a burn fired now would produce, without changing anything. It needs no particular scope. Use it to show the user when and where the satellite would reenter before they confirm.
* <code>POST /api/v1/stations/{id}/deorbit</code> fires the burn and returns the station, now <code>DEORBITING</code>, with its <code>orbit</code> replaced by the post-burn elements (epoch = burn time) and <code>deorbit</code> set. The burn is irreversible.

<syntaxhighlight lang="json">
{
  "burnAt": "2026-10-24T12:00:00Z",
  "reentryAt": "2026-10-24T12:29:00Z",
  "reentryLocation": { "latitudeDeg": -12.3, "longitudeDeg": 101.7, "altitudeMeters": 80000.0 },
  "deltaVMps": 189.0,
  "orbit": {
    "model": "simtx-j2-v1", "epoch": "2026-10-24T12:00:00Z",
    "semiMajorAxisKm": 6596.0, "eccentricity": 0.0493, "inclinationDeg": 97.6,
    "raanDeg": 120.4, "argumentOfPerigeeDeg": 270.0, "meanAnomalyDeg": 180.0
  }
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Description
|-
| <code>burnAt</code> || When the burn fires (or fired).
|-
| <code>reentryAt</code> || The first time after the burn that the height drops below 80 km. Sessions on the satellite end then, and it becomes <code>DEORBITED</code>.
|-
| <code>reentryLocation</code> || The sub-satellite point at <code>reentryAt</code>; <code>altitudeMeters</code> is the 80 km interface.
|-
| <code>deltaVMps</code> || Velocity change of the burn, m/s.
|-
| <code>orbit</code> || The exact post-burn elements (epoch = <code>burnAt</code>) that the service stores, or would store. Draw the fall from them; do not re-plan the burn.
|}

The values in the example are illustrative. Deorbiting a satellite that is already deorbiting is refused with <code>409 already_deorbiting</code>, one that has reentered with <code>409 station_inactive</code>, and a ground station with <code>400 station_invalid</code>. See [[SimTX API/Satellites#Deorbit|Deorbit]].

== Quotas ==
The number of stations an account may own is capped by numeric capabilities of the account: <code>game.owned_stations.N</code> for all active stations, ground and satellite, and <code>game.owned_satellites.N</code> for active satellites. Deorbiting satellites count until they reenter. <code>game.station_sessions.N</code> caps a station's session limits. Defaults: members 100, 25 and 16; supporters 500, 100 and 64. There are no cooldowns. A creation over a quota is refused with <code>409 station_quota_exceeded</code>, with <code>fieldErrors.capability</code> and <code>fieldErrors.limit</code>.

== Errors ==
{| class="wikitable"
! HTTP !! <code>code</code> !! Meaning
|-
| 400 || <code>station_invalid</code> || A field is invalid; <code>message</code> and <code>fieldErrors</code> name it.
|-
| 403 || <code>scope_required</code> || The credential's scope lacks <code>station.manage</code>.
|-
| 403 || <code>permission_denied</code> || The account lacks <code>station.manage</code>.
|-
| 403 || <code>account_credential_required</code> || A service credential was used.
|-
| 404 || <code>station_not_found</code> || Unknown station, or not yours.
|-
| 409 || <code>station_sealed</code> || The change would modify a launched satellite.
|-
| 409 || <code>station_inactive</code> || The satellite has reentered.
|-
| 409 || <code>last_antenna</code> || A station keeps at least one antenna.
|-
| 409 || <code>station_quota_exceeded</code> || <code>fieldErrors</code> name the capability and its limit.
|-
| 409 || <code>satellite_active</code> || Delete refused; deorbit the satellite and wait for its reentry first.
|-
| 409 || <code>already_deorbiting</code> || The burn has already fired.
|-
| 413 || <code>request_too_large</code> || The body is over 2 MiB.
|}

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