Editing SimTX API/Station endpoints (section)

== 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]].