Ground networks: provider spec
A ground station network that serves two read endpoints, what an operator could book and what they already hold, shows up next to every pass Constellation computes for that operator. Booking and cancelling stay in the network's own portal or API: Constellation never books, never cancels and never spends an operator's money.
Constellation Network
───────────── ───────
GET /v1/availability?from=&to=&satellite= ─────▶ [Slot]
what this operator could book
GET /v1/bookings?from=&to=&cursor= ─────▶ {bookings: [Booking], next_cursor}
what this operator holds, outcomes included
Every minute Constellation reads availability for each linked satellite over the next 7 days, and bookings from 2 days back to 14 days ahead, every page. Both endpoints take a window (from, to), not "changed since": every network surveyed can answer a window query.
What an operator sees
Once an operator links the network:
- Passes shows each computed pass on a linked antenna as Bookable (with price and cancel deadline), Booked (with the network's name), Unavailable, or Unknown when the network publishes no availability.
- Rain-fade swap suggests only backups the network sells, and names the booked contact to cancel and its deadline. The operator, or their mission control system (MCS), books the backup and cancels the original in the network's system.
- Outcomes of booked contacts land in telemetry, so every booking grades the pass forecast.
Objects
Slot
| Field | Meaning |
|---|---|
slot_id | The network's id for the slot, or its reservation token |
antenna_ref | The network's antenna or station id |
satellite | NORAD id, an integer |
start_utc, end_utc | The bookable window, RFC 3339 in UTC |
aos_utc, los_utc | Optional: the visibility window, where the network gives it separately |
cancel_deadline_utc | Optional: the last time a booking can be cancelled. When absent, Passes shows no cancel-by time, and a rain-fade swap uses its own lead (15 minutes before the pass unless set) |
price | Optional: {amount, currency, unit, source}, unit is per_minute or per_contact, source is api or contract |
Booking
| Field | Meaning |
|---|---|
booking_id | The network's id for the booking |
antenna_ref, satellite, start_utc, end_utc, aos_utc, los_utc | As on a slot |
state | scheduled, in_progress, completed, failed, provider_failed, cancelled or provider_cancelled |
raw_status | The network's own status string, passed through |
cancel_deadline_utc, price | Optional, as on a slot |
last_updated_utc | Optional |
outcome | Once the booking ends: {status, error, bytes_delivered, data_ref}. status is ok, failed or missed; the others are optional |
provider_failed and provider_cancelled keep who caused a failure, which matters when an operator asks who is accountable for a lost contact. bytes_delivered is optional because few networks report it; data_ref can point at the network's data product or post-pass report instead.
Rules
- Satellites are keyed by NORAD id. Times are UTC, RFC 3339.
- Auth is
Authorization: Bearer <key>, a key the network issues to one operator. Each key sees only that operator's slots and bookings. GET /v1/bookingsreturns every booking on the operator's account in the window, however it was made (portal, API or phone), oldest first. Pages hold up to 500, continued with the opaquenext_cursor, which is null on the last page. A cursor, not a timestamp, so a page boundary never loops when many bookings share one update time.- Responses carry
X-Contract-Version: 0. - Served over https on a public address, with no redirects. Constellation refuses private addresses, plain http and redirects when the link is created, tested and on every call.
- Errors are JSON:
{"error": "...", "message": "..."}.
Identifiers
NORAD id is the satellite key on the wire: each link maps the operator's satellite ids to NORAD ids, and the operator's antenna ids to the network's antenna_ref. A booking is matched to a computed pass by that antenna map, the NORAD id, and a window overlap of at least half the shorter of the two. A booking that matches no pass is not shown.
Worked example: the Sandbox network
The Sandbox network is the reference implementation, and what an operator links to see the integration on the demo fleet. It sells every computed pass of the demo satellites on the demo's third-party stations (Svalbard, Troll, Fairbanks and AWS Ohio), never on the operator's own Singapore teleport and never to a real satellite. A few demo contacts are already booked, so Booked shows too. Its cancel deadline is 15 minutes before AOS.
A slot for NORAD 43013 over the Svalbard antenna sg-x1:
GET /v1/availability?from=2026-11-17T00:00:00Z&to=2026-11-18T00:00:00Z&satellite=43013
Authorization: Bearer <key>
[
{
"slot_id": "sbx-sg-x1-43013-20261117T1620",
"antenna_ref": "sg-x1",
"satellite": 43013,
"start_utc": "2026-11-17T16:20:00Z",
"end_utc": "2026-11-17T16:31:00Z",
"cancel_deadline_utc": "2026-11-17T16:05:00Z",
"price": { "amount": 4.5, "currency": "USD", "unit": "per_minute", "source": "contract" }
}
]
A booked contact that has ended, with its outcome:
GET /v1/bookings?from=2026-11-15T00:00:00Z&to=2026-12-01T00:00:00Z
Authorization: Bearer <key>
{
"bookings": [
{
"booking_id": "sbx-b-0007",
"antenna_ref": "tr-xka1",
"satellite": 43013,
"start_utc": "2026-11-16T09:02:00Z",
"end_utc": "2026-11-16T09:12:00Z",
"state": "completed",
"raw_status": "COMPLETED",
"cancel_deadline_utc": "2026-11-16T08:47:00Z",
"outcome": { "status": "ok", "bytes_delivered": 18400000000 }
}
],
"next_cursor": null
}
The ids, prices and times above illustrate the shapes; the Sandbox's own answers move with the demo's passes.
A network without availability
Some networks list an operator's bookings but publish no availability. A link says so (has_availability: false): passes on its antennas with no booking then read Unknown, "check with" the network, never Unavailable, and a rain-fade swap labels such a backup the same way.
Related
- Ground networks: linking a network, and how passes are computed
- Passes: what a pass is and how it is forecast
- Ground station contention: sharing antennas between satellites