Topology config
The network config, at /topology/config, holds the fixed facts about your links: ground stations with their antennas, and satellites with their radios. Upload it with PUT, change parts of it with PATCH, and read any version back with GET.
Before you begin
Create an API key with the config:write scope. See Authentication.
Endpoints
| Method and path | Purpose | Required scope |
|---|---|---|
PUT /topology/config | Replace the whole document. | config:write |
PATCH /topology/config | Change parts of the document with a JSON merge patch. | config:write |
GET /topology/config | Read the latest version, or an older one with version. | config:read, config:write or workflows:write |
POST /topology/demo-fleet | Load the demo fleet into an account whose network config holds no station, antenna or satellite, or holds the demo fleet already. | config:write |
DELETE /topology/demo-fleet | Remove the demo fleet: its satellites, stations, workflows and telemetry. Your own entities stay. | config:write |
GET /assets/satellites, GET /assets/stations | Search the public asset catalog to build your fleet from. | topology:read |
Example document
This document has one ground station, one antenna with one downlink frequency range, and one satellite with one downlink radio. It sets every field that would raise an issue, so the write responses have an empty issues list. Replace the IDs and values with your own. NORAD ID 25544 is an example; use the NORAD ID of your satellite.
Save the document as topology-config.json for the examples below.
{
"ground_stations": {
"gs-1": {
"latitude_deg": 43.2965,
"longitude_deg": 5.3698,
"altitude_m": 100,
"antennas": {
"ant-1": {
"band": "Ka",
"min_elevation_deg": 5,
"frequency_ranges": {
"ka-rx": {
"direction": "downlink",
"min_ghz": 17.7,
"max_ghz": 20.2,
"g_t_db_k": 18.5,
"g_t_elevation_deg": 10
}
}
}
}
}
},
"satellites": {
"sat-1": {
"norad_id": 25544,
"radios": {
"ka-dl-1": {
"direction": "downlink",
"band": "Ka",
"frequency_ghz": 19.5,
"bandwidth_mhz": 250,
"polarization": "rhcp",
"eirp_dbw": 52.0
}
}
}
}
}
Fields
Ground station
| Field | Unit | Required | Description |
|---|---|---|---|
latitude_deg | deg | Yes, unless a catalog pick fills it | Latitude, from -90 to 90. |
longitude_deg | deg | Yes, unless a catalog pick fills it | Longitude, from -180 to 180. |
altitude_m | m | No | Height above mean sea level, from -500 to 9000. Without it, 0 m is used. |
antennas | object | No | The antennas at this station, keyed by antenna ID. |
catalog | object | No | A pick from the asset catalog, as {"station_id": "ksat/svalbard"}. The write fills the position and receive_ranges when you leave them out. |
receive_ranges | list | No | The receive ranges the catalog publishes for the site, filled from a pick. For reference only: links use your antennas' frequency ranges. |
maintenance | list | No | Planned maintenance that recurs every day, as [{"daily_utc": "06:00", "minutes": 180, "reason": "..."}]. A run drops every pass of the station's antennas that overlaps a window, and never offers one as a swap backup. |
Antenna
| Field | Unit | Required | Description |
|---|---|---|---|
band | none | No | The IEEE Std 521 band letter: HF, VHF, UHF, L, S, C, X, Ku, K, Ka, V, or W, or optical for 3,000 GHz and above. |
min_elevation_deg | deg | No | The elevation mask: the lowest elevation the antenna tracks at. From -5 to below 90. Without it, 0 deg is used. |
antenna_diameter_m | m | No | Above 0, and at most 100. |
antenna_efficiency | fraction | No | Above 0, and at most 1. |
mount_type | none | No | The antenna's axes: az_el, x_y or az_el_xel. |
sun_coupling | fraction | No | From 0 to 1: the antenna temperature over a disk's brightness temperature with the whole main beam on the Sun or Moon, measured from a transit. The RF interference model uses it for Sun and Moon noise. |
acquisition_s | s | No | From the start of a pass to modem lock. A pass carries nothing before it, so its expected GB counts only the time after. Without it, 0 s is used. |
slew_rate_deg_s | deg/s | No | How fast the antenna turns, as {"az": 5, "el": 2.5}. Stored and shown on Fleet. |
frequency_ranges | object | No | The bands the antenna receives or transmits, keyed by range ID. |
Frequency range
| Field | Unit | Required | Description |
|---|---|---|---|
direction | none | For RF values | downlink or uplink. Without it, the range gives no RF values. |
min_ghz | GHz | For RF values | Lower edge of the band. Must be below max_ghz. |
max_ghz | GHz | For RF values | Upper edge of the band. |
g_t_db_k | dB/K | No | Downlink only. The ground G/T from the datasheet, under clear sky. |
g_t_elevation_deg | deg | No | Downlink only. The elevation at which the datasheet states G/T, from 0 to 90. Omit it if the datasheet states none. |
eirp_dbw | dBW | No | Uplink only. The ground station's maximum EIRP. |
half_power_beamwidth_deg | deg | No | The measured half-power beamwidth over this range, from a beam scan or the datasheet. Above 0, at most 90. The SSA and RF interference models use it in place of 70 wavelengths over the dish diameter. |
Satellite
| Field | Unit | Required | Description |
|---|---|---|---|
norad_id | none | One of norad_id or tle | The NORAD catalog number, from 1 to 999,999,999. The orbit comes from the public catalog entry for this number. |
tle | object | One of norad_id or tle | Your own two-line element set, as line1 and line2, each 69 characters. Use it for a satellite the public catalog does not hold, or an orbit you fit yourself. The satellite's NORAD ID is the one in line 1. |
radios | object | No | The carriers the satellite transmits or receives, keyed by radio ID. |
catalog | object | No | A pick from the asset catalog, as {"norad_id": 43013}. The write fills the fields below that you leave out. |
name, operator, fleet | text | No | Labels. Filled from a catalog pick when you leave them out. Nothing is priced from them. |
downlink_ranges | list | No | The downlink ranges the catalog publishes (min_ghz, max_ghz, band), filled from a pick. For reference only: links pair radios with antenna frequency ranges, never with these. |
Give a satellite exactly one of norad_id or tle. A satellite with a tle:
"sat-1": {
"tle": {
"line1": "1 44714U 19074B 26016.00002315 .00082898 00000+0 44081-2 0 9990",
"line2": "2 44714 53.0838 63.0449 0001350 116.5282 165.6258 15.14557594 5744"
},
"radios": { ... }
}
A tle is used however old its epoch, and its orbit error grows the further a forecast is from that epoch. Replace it with PATCH whenever you have a newer one.
Radio
| Field | Unit | Required | Description |
|---|---|---|---|
direction | none | For RF values | downlink or uplink. Without it, the radio gives no RF values. |
band | none | No | The IEEE Std 521 band letter, from the same list as the antenna's band. |
frequency_ghz | GHz | For RF values | The nominal center frequency of the carrier. |
bandwidth_mhz | MHz | No | The nominal occupied bandwidth. Above 0. |
polarization | none | No | rhcp, lhcp, linear_horizontal, or linear_vertical. |
eirp_dbw | dBW | No | Downlink only. The satellite's peak EIRP at beam center. |
g_t_db_k | dB/K | No | Uplink only. The satellite's G/T. |
modcod | object | No | How the modem chooses modulation and coding: standard (dvb-s2x, dvb-s2 or other), adaptive (boolean) and required_es_n0_db (-15 to 40, the Es/N0 the modem needs; required when adaptive is false or standard is other). Without it, the radio is DVB-S2X with adaptive coding and modulation. |
modcods | list | No | The carrier's MODCOD table, each entry with name, min_es_n0_db and efficiency_bps_hz. Without it, the radio is priced on a generic DVB-S2 table. |
Dual polarization takes two radios. RF values in the document are nominal datasheet values.
IDs
You choose every ID. Each ID matches ^[A-Za-z0-9._-]{1,64}$.
- IDs are scoped to your tenant. Antenna IDs must be unique across all ground stations, and NORAD IDs across all satellites, whether given as
norad_idor in atle. - A satellite with no other name can use
norad-<NORAD ID>, for examplenorad-25544. - Renaming an ID starts that entity fresh.
Replace the document
PUT /topology/config replaces the whole document. The body is the document itself, not a wrapper. Each write that changes the document stores a new numbered version and returns 201. A write that stores the same document as the latest version returns 200 with that version. Key order does not count.
curl --fail-with-body -sS -X PUT \
-H "x-api-key: $CONSTELLATION_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @topology-config.json \
"https://api.constellation.space/topology/config"
{
"version": 1,
"created_at": "2026-10-26T12:00:00Z",
"created_by": "key-example",
"issues": []
}
created_by identifies the caller. The tenant comes from your API key, not from the body.
Change part of the document
PATCH /topology/config applies a JSON merge patch to the latest version. A value sets or merges its key, null deletes it, and a key you omit is kept. The merged document is validated like a PUT. This example sets the minimum elevation of ant-1 to 10 degrees:
curl --fail-with-body -sS -X PATCH \
-H "x-api-key: $CONSTELLATION_API_KEY" \
-H "Content-Type: application/merge-patch+json" \
-d '{"ground_stations": {"gs-1": {"antennas": {"ant-1": {"min_elevation_deg": 10}}}}}' \
"https://api.constellation.space/topology/config"
{
"version": 2,
"created_at": "2026-10-26T12:05:00Z",
"created_by": "key-example",
"issues": []
}
To delete the satellite sat-1, send {"satellites": {"sat-1": null}}.
Read the document
GET /topology/config returns the latest version. Add version to read an older one.
curl --fail-with-body -sS \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/topology/config?version=1"
{
"version": 1,
"created_at": "2026-10-26T12:00:00Z",
"created_by": "key-example",
"document": { "ground_stations": { ... }, "satellites": { ... } },
"issues": [],
"readiness": { ... }
}
Asset catalog
You can build your fleet from the public asset catalog instead of typing every field: the satellites and ground stations operators publish, with their bands, operators and positions. Search it, add a pick to your network config, and enter only what the catalog cannot know, such as radio EIRP and antenna G/T. The guide Build your fleet from the catalog walks through it, and Fleet in Platform does it with a search box.
Search
| Route | Filters |
|---|---|
GET /assets/satellites | q (name, NORAD ID or operator, any case), operator, fleet, band (S, X or Ka) |
GET /assets/stations | q (station ID, owner or site), operator (the owner), band, near (lat,lon in degrees) with within_km (default 500) |
Both take limit (1 to 200, default 50) and cursor. Results that start a word with q come first, then those holding it anywhere. With near, stations come nearest first, each with its distance_km.
curl --fail-with-body -sS \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/assets/satellites?q=noaa%2020&limit=5"
{
"catalog_version": "9f2c...",
"total": 1,
"items": [
{
"norad_id": 43013,
"name": "NOAA 20 (JPSS-1)",
"operator": "noaa",
"fleet": "jpss",
"launched_on": "2017-11-18",
"bands": [{ "low_mhz": 7787.0, "high_mhz": 7837.0, "letter": "X" }]
}
],
"next_cursor": null
}
A station item has station_id, owner, site, latitude_deg, longitude_deg, bands and antennas (low and high counts, where published). Pass next_cursor as cursor for the next page. The catalog changes only with a release: answers carry the catalog version as their ETag and may be cached for an hour, and a request with that ETag in If-None-Match gets 304.
Add a pick
Give a satellite "catalog": {"norad_id": N} or a ground station "catalog": {"station_id": "ksat/svalbard"} in a PUT or PATCH. The write fills what you leave out:
| Pick | Filled when absent |
|---|---|
| Satellite | norad_id, name, operator, fleet, downlink_ranges |
| Ground station | latitude_deg, longitude_deg, receive_ranges |
curl --fail-with-body -sS -X PATCH \
-H "x-api-key: $CONSTELLATION_API_KEY" \
-H "Content-Type: application/merge-patch+json" \
-d '{"satellites": {"norad-43013": {"catalog": {"norad_id": 43013},
"radios": {"x-hrd": {"direction": "downlink", "band": "X", "frequency_ghz": 7.812, "bandwidth_mhz": 30, "eirp_dbw": 1.2}}}}}' \
"https://api.constellation.space/topology/config"
Your own fields always win: a value you send is kept, whatever the catalog says. The catalog never fills an RF value (EIRP, G/T, carrier frequency, bandwidth, MODCOD), an antenna or a radio. The stored version is complete on its own and records the catalog_version it was filled from, and so does each workflow run. Each pick lists the fields the catalog filled in its filled, which the API sets.
| Your write | What happens to the fields the catalog filled |
|---|---|
| The pick names another asset | They are cleared and filled from the new pick, with PUT or PATCH. |
A PATCH sends the pick again | They are refilled from the current catalog. This is how to refresh. |
A PUT of the whole document | The same: the document carries every pick, so reading it and putting it back refreshes it. |
A PATCH without the pick | They stay as they are. |
A field you set yourself is never cleared or overwritten. To refresh one satellite:
curl --fail-with-body -sS -X PATCH \
-H "x-api-key: $CONSTELLATION_API_KEY" \
-H "Content-Type: application/merge-patch+json" \
-d '{"satellites": {"norad-43013": {"catalog": {"norad_id": 43013}}}}' \
"https://api.constellation.space/topology/config"
PATCH, with a button such as Refresh 3 from catalog.
Readiness
GET /topology/config also returns readiness: for each satellite and ground station, whether each lane can price it, and what is missing.
"readiness": {
"satellites": {
"norad-43013": {
"snr": { "ready": false, "missing": ["eirp_dbw"] },
"weather": { "ready": true },
"demand": { "ready": true },
"rfi": { "ready": true },
"ssa": { "ready": true }
}
},
"ground_stations": { "nasa-fairbanks": { "snr": { "ready": false, "missing": ["g_t_db_k"] } } }
}
missing names the fields to add. reason says why a lane cannot price the asset whatever you add:
| Reason | Meaning |
|---|---|
no_antenna_on_band | No antenna in your network config receives the satellite's band. |
orbit_unknown | No element set for the satellite's NORAD ID right now. |
no_passes | A geostationary satellite never sets, so demand has no pass to price. |
orbit_not_in_range | SSA is measured for perigee from 400 km and apogee under 2,000 km, Starlink excepted. |
orbit_invalid | The satellite's stored element set has a mean motion that is not positive, so it has no orbit. Demand and SSA cannot price it; give it a valid tle. |
Readiness is read from your fields and the public orbit catalog; no model runs to compute it.
Load the demo fleet
No fleet of your own yet? POST /topology/demo-fleet loads a ready-made one: 5 ground stations with 7 antennas and 6 Earth observation satellites, 5 sun-synchronous and 1 geostationary (NOAA 20, NOAA 21, Suomi NPP, Landsat 9 and Sentinel-2C on X and Ka band, and GOES 19 on its L-band broadcast) as your network config, then the telemetry of its passes in the last two hours, ending now. The stations are polar (Svalbard, Troll, Fairbanks), mid-latitude (Ohio) and tropical (Singapore), an antenna works only the satellites on its bands, and the polar sites see a pass every orbit. GOES 19 is in view of Ohio's L-band antenna all the time: Passes shows it as one continuous link with its GB per day, apart from the pass counts and totals. Troll goes down for planned maintenance every day from 06:00 to 09:00 UTC, and a rain cell crosses Singapore every day from 17:00 to 20:00 UTC, so a rain-fade swap is always waiting in the next 48 hours. Every lane can price every sun-synchronous demo satellite; GOES 19 never sets, so demand has no pass to price for it (no_passes). It is the same fleet the MCP tool load_demo_fleet loads and the Hugging Face dataset holds. In Platform, Fleet, Passes (the audit under Past too), Scenarios on Forecasts and the workflow builder offer the same thing as a Load the demo fleet button when the account has no fleet yet, next to Start from the catalog.
The request has no body. It needs config:write; with telemetry:write too, it also posts the telemetry. The mission names, NORAD ids, orbits and station sites are real and public; the antennas, RF terms, acquisition and slew times, maintenance, the rain cell, telemetry gaps and pass outcomes are nominal or simulated, and none of it is telemetry from, or access to, these missions. The telemetry never counts toward the account's telemetry usage.
The load also saves the workflows pass-yield and rain-fade-swap, marked "demo": true, under any of those slugs the account has not used, and starts one run of each over the next 48 hours with the same key (POST /predictions, which needs workflows:write). The plan sets the run as for any other: a test run on Explore, a delivering run above it. The response's workflows says, per slug, whether it was saved and how the run's start was answered. A workflow already saved under either slug is left as it is. A reload saves nothing more, and runs a demo workflow again only when its newest run ends less than 24 hours ahead. A network config write that removes the last demo satellite and antenna removes the workflows still marked demo; saving one without the mark, as the builder does, keeps it.
curl --fail-with-body -sS -X POST \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/topology/demo-fleet"
| Status | Body | Meaning |
|---|---|---|
200 | {"network_config": {...}, "telemetry": {...}, "workflows": {...}} | The demo network config is in place. telemetry counts the records accepted and rejected. When the telemetry post is refused, it holds that refusal's status and body instead, such as 403 (insufficient_scope for a key without telemetry:write, or account_disabled), 429 or 503, and the network config still loads. |
403 | insufficient_scope | The key lacks config:write. Nothing is written. |
409 | {"error": "network_config_exists"} | The account has a network config of its own. It is left as it is, and the demo fleet is not loaded. |
If the network config cannot be merged, the response is that write's error, such as 422 invalid_network_config. A refused telemetry post never changes the 200: check telemetry in the body, and load again to post the telemetry.
Loading again is safe: a network config that already holds the demo fleet is kept, and gains only the demo stations and satellites it lacks, such as ones added to the demo since the account loaded it. An account that still holds the demo's retired definition (six geostationary satellites and NOAA-20) loses the entries it never edited, so a reload swaps it for today's demo. Your edits to demo entries are never overwritten. The telemetry is written again to end at the new present; the Platform does it once a session while the workspace holds only the demo. You do not need to reload before forecasting: ask for SNR by at, at a time inside a pass that GET /topology/passes lists. The five polar orbiters are in low orbit, so a link has telemetry from the last minute only during a pass, and latest SNR by link answers no_telemetry between passes.
?reset=true also puts today's demo back over each demo satellite and station the account edited, and starts a new run of each demo workflow. The account's own entities stay, as does a demo station holding an antenna of the account's own.
An edited demo antenna becomes yours: it no longer counts as the demo's, the demo's planted rain never reaches it, and removing the demo keeps it.
The demo fleet's satellites do not count toward a plan's satellite limit, so Explore loads all 6, and neither today's demo nor the retired one an account already held counts toward the bill. Only a demo load marks an entity as the demo's: the demo's definitions sent in a network config write count as the account's own, as does a demo satellite moved to another NORAD id. Workflow runs on Explore cover at most 2 satellites of your own, the demo's not counted; see Plans and limits.
Remove the demo fleet
DELETE /topology/demo-fleet removes the demo fleet from the account: the satellites and stations still marked as the demo's, and the workflows marked "demo": true. The demo's simulated telemetry is not deleted; it names only the demo's antennas, so nothing reads it once they are gone, and it ages out with retention. The account's own satellites, stations and workflows stay, and so does anything of the demo's that has become the account's own, such as an edited antenna or a satellite moved to another NORAD id. The request has no body and needs config:write.
curl --fail-with-body -sS -X DELETE \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/topology/demo-fleet"
| Status | Body | Meaning |
|---|---|---|
204 | None | The demo fleet is gone, or the account held none. Safe to repeat. |
401 | unauthorized | The key is missing or not valid. |
403 | insufficient_scope | The key lacks config:write. Nothing is removed. |
On Platform, Remove the demo does the same, after asking first.
Issues
Issues describe gaps in a stored document. They never block a write. Each issue has a code, a path that points at the field as a JSON Pointer, and a message.
| Code | Points at | Effect |
|---|---|---|
unknown_field | The field | Dropped, and not stored. |
no_altitude | The ground station | 0 m is used. |
no_mask | The antenna | 0 deg is used for min_elevation_deg. |
no_rf | A satellite with no radios, or an antenna with no frequency_ranges | It gives no RF values. |
incomplete_range | The frequency range | direction, min_ghz, or max_ghz is missing. It gives no RF values. |
incomplete_radio | The radio | direction or frequency_ghz is missing. It gives no RF values. |
radio_without_link | The radio | No frequency range of the antenna contains its frequency. |
no_budget | The radio | A term of the link budget is missing: satellite EIRP and ground G/T on a downlink, satellite G/T and ground EIRP on an uplink, or bandwidth_mhz. An optical downlink needs EIRP and the antenna's antenna_diameter_m and antenna_efficiency. |
band_frequency_mismatch | The frequency range or radio | Its band letter disagrees with its frequency: optical is 3,000 GHz or more. It is often a frequency typed in THz. |
no_polarization | The radio | Polarization is not set, so circular polarization is assumed. |
catalog_coordinates_differ | The ground station | Its coordinates are over 5 km from its catalog pick's. Yours are kept. |
catalog_changed | /catalog_version | The picks were filled from an earlier catalog. PATCH each pick again to refresh them; your own values stay. |
Errors
| Status | Body | Cause and action |
|---|---|---|
401, 403 | auth_failed or insufficient_scope | The key is invalid, or it lacks the scope the route needs: config:write to write, or config:read, config:write or workflows:write to read. See Errors and limits. |
403 | {"error": "plan_required", "plan": "standard", "feature": "satellites"} | The write adds satellites past Explore's 2. The demo fleet's satellites do not count, and a config already past 2 keeps working; only adding more is refused. Upgrade to Operator. |
404 | {"error": "no_network_config"} | Nothing has been uploaded, or the version does not exist. |
409 | {"error": "version_conflict"} | A concurrent write took the version number. Retry the write. |
413 | {"error": "network_config_too_large", "limit_bytes": 358400} | The body, or the document a PATCH would store, is over the limit. Reduce the document. |
422 | {"error": "invalid_network_config", "errors": [...]} | The document has at least one error. Fix each error at its path, then resend. |
429 | rate_limited or auth_lockout | Honor Retry-After. See Errors and limits. |
503 | {"error": "plan_unavailable"} | The plan a growing fleet is checked against could not be read. Retry with backoff. |
The errors list in a 422 response holds every error the check found, not only the first. Errors are found in stages, and the first stage with any stops the check: the JSON itself, catalog picks, non-finite numbers, schema, then the rest. Each error has a code:
| Code | Meaning |
|---|---|
non_finite_number | A number is NaN or infinite; path names the field. When any is, the response lists only these errors. |
schema | A required field is missing, a satellite has both or neither of norad_id and tle, a value has the wrong type or is out of range, an ID breaks the pattern, or a frequency range or radio carries the RF term of the other direction, such as eirp_dbw on a downlink range. |
duplicate_key | The JSON body repeats a key within one object. |
duplicate_antenna_id | Two ground stations hold an antenna with the same ID. |
duplicate_norad_id | Two satellites share a NORAD ID, given as norad_id or in line 1 of a tle. |
invalid_tle | The tle cannot be read: a checksum is wrong, the two lines carry different NORAD IDs, a field is malformed, or its mean motion is not positive. |
overlapping_frequency_ranges | One antenna has two frequency ranges of the same direction whose bands overlap. |
inverted_frequency_range | A frequency range has min_ghz at or above max_ghz. |
unknown_catalog_id | A catalog pick names no satellite or station in the catalog. |
catalog_norad_id_differs | A satellite's norad_id, or the NORAD ID in line 1 of its tle, is not its catalog pick's. |
Limits
| Limit | Value |
|---|---|
| Document size | 358,400 bytes |
| Ground stations | 1,000 |
| Satellites | 5,000 |
| Antennas per ground station | 100 |
| Frequency ranges per antenna | 20 |
| Radios per satellite | 50 |
A document over a count limit is rejected with 422 and invalid_network_config.