HTTP API overview

The Axum service exposes the same engine as the CLI over HTTP. It is what the web UI talks to, and it is the integration point for anything that is not a shell.

orbitforge-api
# listens on 127.0.0.1:8080 by default

Read this before your first request

Three behaviors cause more lost time than anything else in this API, and none of them produces an error.

Behavior 1 and behavior 3 interact badly. Putting frequency_ghz at the top level instead of inside rf is ignored, so the request succeeds and quietly uses the default 12 GHz. Putting it inside rf alone fails loudly with rf: missing field tx_power_dbw. The failing case is the safer one.

Conventions

The service is stateful

This is the most important structural fact about the API. Constellations and scenarios live in the service’s memory and are addressed by identifier.

Analysis endpoints take a constellation_id, not a constellation document. You create the constellation once, then run many analyses against it.

Endpoint groups

Errors

Application errors return a consistent envelope:

{
  "error": {
    "code": "not_found",
    "message": "constellation `nope` not found; generate it first"
  }
}

Deserialization failures do not. They return 422 with a plain-text body:

Failed to deserialize the JSON body into the target type: missing field `ground_stations` at line 1 column 174

The plain-text 422 is genuinely useful once you expect it: it names the missing field and its position, which is how the all-or-nothing behavior of nested config objects gets diagnosed.

A minimal session

API=http://127.0.0.1:8080
 
curl -s $API/health
 
curl -s -X POST $API/constellations/walker \
  -H 'content-type: application/json' \
  -d '{"name":"demo","planes":6,"sats_per_plane":10,
       "altitude_km":550.0,"inclination_deg":53.0,"fov_deg":45.0}'
 
curl -s -X POST $API/simulate \
  -H 'content-type: application/json' \
  -d '{"constellation_id":"demo","duration_hours":6.0,
       "step_seconds":60.0,"propagation_model":"two_body"}'
 
curl -s $API/scenarios/scenario-demo

{"status":"ok","service":"orbitforge-api","version":"0.1.0"}
{"constellation_id":"demo","name":"demo","satellite_count":60}
{"scenario_id":"scenario-demo","status":"completed","satellite_count":60,"sample_count":361,"czml_url":"/api/scenarios/scenario-demo/czml"}
{"scenario_id":"scenario-demo","name":"demo","start_time":"2026-01-01T00:00:00Z","duration_seconds":21600.0,"step_seconds":60.0,"model":"two_body","satellite_count":60,"sample_count":361}

See also

• CLI overview for the same engine from a shell.
• Units and conventions.