Skip to main content

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 pathPurposeRequired scope
PUT /topology/configReplace the whole document.config:write
PATCH /topology/configChange parts of the document with a JSON merge patch.config:write
GET /topology/configRead the latest version, or an older one with version.config:read, config:write or workflows:write
POST /topology/demo-fleetLoad 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-fleetRemove the demo fleet: its satellites, stations, workflows and telemetry. Your own entities stay.config:write
GET /assets/satellites, GET /assets/stationsSearch 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​

FieldUnitRequiredDescription
latitude_degdegYes, unless a catalog pick fills itLatitude, from -90 to 90.
longitude_degdegYes, unless a catalog pick fills itLongitude, from -180 to 180.
altitude_mmNoHeight above mean sea level, from -500 to 9000. Without it, 0 m is used.
antennasobjectNoThe antennas at this station, keyed by antenna ID.
catalogobjectNoA pick from the asset catalog, as {"station_id": "ksat/svalbard"}. The write fills the position and receive_ranges when you leave them out.
receive_rangeslistNoThe receive ranges the catalog publishes for the site, filled from a pick. For reference only: links use your antennas' frequency ranges.
maintenancelistNoPlanned 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​

FieldUnitRequiredDescription
bandnoneNoThe 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_degdegNoThe elevation mask: the lowest elevation the antenna tracks at. From -5 to below 90. Without it, 0 deg is used.
antenna_diameter_mmNoAbove 0, and at most 100.
antenna_efficiencyfractionNoAbove 0, and at most 1.
mount_typenoneNoThe antenna's axes: az_el, x_y or az_el_xel.
sun_couplingfractionNoFrom 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_ssNoFrom 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_sdeg/sNoHow fast the antenna turns, as {"az": 5, "el": 2.5}. Stored and shown on Fleet.
frequency_rangesobjectNoThe bands the antenna receives or transmits, keyed by range ID.

Frequency range​

FieldUnitRequiredDescription
directionnoneFor RF valuesdownlink or uplink. Without it, the range gives no RF values.
min_ghzGHzFor RF valuesLower edge of the band. Must be below max_ghz.
max_ghzGHzFor RF valuesUpper edge of the band.
g_t_db_kdB/KNoDownlink only. The ground G/T from the datasheet, under clear sky.
g_t_elevation_degdegNoDownlink only. The elevation at which the datasheet states G/T, from 0 to 90. Omit it if the datasheet states none.
eirp_dbwdBWNoUplink only. The ground station's maximum EIRP.
half_power_beamwidth_degdegNoThe 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​

FieldUnitRequiredDescription
norad_idnoneOne of norad_id or tleThe NORAD catalog number, from 1 to 999,999,999. The orbit comes from the public catalog entry for this number.
tleobjectOne of norad_id or tleYour 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.
radiosobjectNoThe carriers the satellite transmits or receives, keyed by radio ID.
catalogobjectNoA pick from the asset catalog, as {"norad_id": 43013}. The write fills the fields below that you leave out.
name, operator, fleettextNoLabels. Filled from a catalog pick when you leave them out. Nothing is priced from them.
downlink_rangeslistNoThe 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​

FieldUnitRequiredDescription
directionnoneFor RF valuesdownlink or uplink. Without it, the radio gives no RF values.
bandnoneNoThe IEEE Std 521 band letter, from the same list as the antenna's band.
frequency_ghzGHzFor RF valuesThe nominal center frequency of the carrier.
bandwidth_mhzMHzNoThe nominal occupied bandwidth. Above 0.
polarizationnoneNorhcp, lhcp, linear_horizontal, or linear_vertical.
eirp_dbwdBWNoDownlink only. The satellite's peak EIRP at beam center.
g_t_db_kdB/KNoUplink only. The satellite's G/T.
modcodobjectNoHow 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.
modcodslistNoThe 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_id or in a tle.
  • A satellite with no other name can use norad-<NORAD ID>, for example norad-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.

RouteFilters
GET /assets/satellitesq (name, NORAD ID or operator, any case), operator, fleet, band (S, X or Ka)
GET /assets/stationsq (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:

PickFilled when absent
Satellitenorad_id, name, operator, fleet, downlink_ranges
Ground stationlatitude_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 writeWhat happens to the fields the catalog filled
The pick names another assetThey are cleared and filled from the new pick, with PUT or PATCH.
A PATCH sends the pick againThey are refilled from the current catalog. This is how to refresh.
A PUT of the whole documentThe same: the document carries every pick, so reading it and putting it back refreshes it.
A PATCH without the pickThey 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"
When the catalog has changed, Fleet in Platform refreshes every picked asset in one 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:

ReasonMeaning
no_antenna_on_bandNo antenna in your network config receives the satellite's band.
orbit_unknownNo element set for the satellite's NORAD ID right now.
no_passesA geostationary satellite never sets, so demand has no pass to price.
orbit_not_in_rangeSSA is measured for perigee from 400 km and apogee under 2,000 km, Starlink excepted.
orbit_invalidThe 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"
StatusBodyMeaning
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.
403insufficient_scopeThe 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"
StatusBodyMeaning
204NoneThe demo fleet is gone, or the account held none. Safe to repeat.
401unauthorizedThe key is missing or not valid.
403insufficient_scopeThe 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.

CodePoints atEffect
unknown_fieldThe fieldDropped, and not stored.
no_altitudeThe ground station0 m is used.
no_maskThe antenna0 deg is used for min_elevation_deg.
no_rfA satellite with no radios, or an antenna with no frequency_rangesIt gives no RF values.
incomplete_rangeThe frequency rangedirection, min_ghz, or max_ghz is missing. It gives no RF values.
incomplete_radioThe radiodirection or frequency_ghz is missing. It gives no RF values.
radio_without_linkThe radioNo frequency range of the antenna contains its frequency.
no_budgetThe radioA 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_mismatchThe frequency range or radioIts band letter disagrees with its frequency: optical is 3,000 GHz or more. It is often a frequency typed in THz.
no_polarizationThe radioPolarization is not set, so circular polarization is assumed.
catalog_coordinates_differThe ground stationIts coordinates are over 5 km from its catalog pick's. Yours are kept.
catalog_changed/catalog_versionThe picks were filled from an earlier catalog. PATCH each pick again to refresh them; your own values stay.

Errors​

StatusBodyCause and action
401, 403auth_failed or insufficient_scopeThe 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.
429rate_limited or auth_lockoutHonor 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:

CodeMeaning
non_finite_numberA number is NaN or infinite; path names the field. When any is, the response lists only these errors.
schemaA 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_keyThe JSON body repeats a key within one object.
duplicate_antenna_idTwo ground stations hold an antenna with the same ID.
duplicate_norad_idTwo satellites share a NORAD ID, given as norad_id or in line 1 of a tle.
invalid_tleThe 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_rangesOne antenna has two frequency ranges of the same direction whose bands overlap.
inverted_frequency_rangeA frequency range has min_ghz at or above max_ghz.
unknown_catalog_idA catalog pick names no satellite or station in the catalog.
catalog_norad_id_differsA satellite's norad_id, or the NORAD ID in line 1 of its tle, is not its catalog pick's.

Limits​

LimitValue
Document size358,400 bytes
Ground stations1,000
Satellites5,000
Antennas per ground station100
Frequency ranges per antenna20
Radios per satellite50

A document over a count limit is rejected with 422 and invalid_network_config.