Constellations

POST/constellations/walker

Purpose

Generates a Walker constellation and registers it in the service. The returned constellation_id is what every analysis endpoint consumes; nothing takes a constellation document inline.

This is normally the first call in a session.

Request

Parameter	Type	Unit	Default	Required	Description
`name`	string	n/a	—	Yes	Constellation name. Becomes the `constellation_id` and prefixes satellite identifiers.
`planes`	integer	count	—	Yes	Number of orbital planes.
`sats_per_plane`	integer	count	—	Yes	Satellites per plane. Note the abbreviation; the CLI flag is `--sats-per-plane`.
`altitude_km`	number	km	—	Yes	Orbit altitude above the reference ellipsoid.
`inclination_deg`	number	deg	—	Yes	Inclination. Sets a hard ceiling on the latitude that can be covered.
`fov_deg`	number	deg	`45`	No	Payload field of view, used later for coverage footprints.
`pattern`	string	n/a	`delta`	No	`delta` spreads RAAN over 360 degrees; `star` over 180.
`phasing`	integer	n/a	`1`	No	Inter-plane phasing factor F, where 0 <= F < planes.

Example


curl -s -X POST http://127.0.0.1:8080/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
      }'


{ "constellation_id": "demo", "name": "demo", "satellite_count": 60 }

The identifier is derived from the name, until it collides

On the first use of a name, constellation_id is a slug of that name. On a second use of the same name, the service does not overwrite: it creates a new constellation and appends a UTC timestamp to both the identifier and the name.


curl -s -X POST http://127.0.0.1:8080/constellations/walker \
  -H 'content-type: application/json' \
  -d '{"name":"probe1","planes":2,"sats_per_plane":2,
       "altitude_km":550.0,"inclination_deg":53.0}'


{ "constellation_id": "probe1", "name": "probe1", "satellite_count": 4 }

Running the identical request again:


{
  "constellation_id": "probe1-2026-08-15t20-34-29z",
  "name": "probe1 2026-08-15T20:34:29Z",
  "satellite_count": 4
}

Do not assume the identifier you asked for is the identifier you got. A client that hard-codes constellation_id: "demo" after a create will work the first time and address a stale constellation on every subsequent run, because the newer one has a timestamped identifier.

Always read constellation_id from the response and use that value. This is the single most likely way to spend an afternoon analyzing the wrong constellation.

The behavior is deliberate: it prevents an accidental repeat from destroying a constellation other work is still referencing. The cost is that identifiers are not predictable, so they must be captured rather than constructed.

Names should also be URL-safe, because the identifier appears in paths such as /fleets/{constellation_id}/reconcile.

Satellite identifiers follow <name>-s0-p<plane>-sat<index>, for example demo-s0-p00-sat00. Error messages from other endpoints name satellites this way, so the identifier tells you which plane and slot failed.

Constellations live in the service’s memory. Restarting the process loses them, and a 404 from an analysis endpoint on an identifier you know you created almost always means a restart rather than a typo.

Field naming differs from the CLI

Concept	CLI flag	API field
Satellites per plane	`--sats-per-plane`	`sats_per_plane`
Altitude	`--altitude-km`	`altitude_km`
Inclination	`--inclination-deg`	`inclination_deg`
Field of view	`--fov-deg`	`fov_deg`

The mapping is mechanical, hyphens to underscores, but an unknown field is ignored rather than rejected, so satsPerPlane or sats-per-plane would be silently dropped. Because sats_per_plane is required, that particular mistake does fail loudly with a 422; a mistyped optional field would not.

Next steps

The identifier feeds every analysis endpoint:


curl -s -X POST http://127.0.0.1:8080/simulate \
  -H 'content-type: application/json' \
  -d '{"constellation_id":"demo","duration_hours":6.0,
       "step_seconds":60.0,"propagation_model":"two_body"}'


{
  "scenario_id": "scenario-demo",
  "status": "completed",
  "satellite_count": 60,
  "sample_count": 361,
  "czml_url": "/api/scenarios/scenario-demo/czml"
}