Skip to main content

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​

FieldMeaning
slot_idThe network's id for the slot, or its reservation token
antenna_refThe network's antenna or station id
satelliteNORAD id, an integer
start_utc, end_utcThe bookable window, RFC 3339 in UTC
aos_utc, los_utcOptional: the visibility window, where the network gives it separately
cancel_deadline_utcOptional: 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)
priceOptional: {amount, currency, unit, source}, unit is per_minute or per_contact, source is api or contract

Booking​

FieldMeaning
booking_idThe network's id for the booking
antenna_ref, satellite, start_utc, end_utc, aos_utc, los_utcAs on a slot
statescheduled, in_progress, completed, failed, provider_failed, cancelled or provider_cancelled
raw_statusThe network's own status string, passed through
cancel_deadline_utc, priceOptional, as on a slot
last_updated_utcOptional
outcomeOnce 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​

  1. Satellites are keyed by NORAD id. Times are UTC, RFC 3339.
  2. Auth is Authorization: Bearer <key>, a key the network issues to one operator. Each key sees only that operator's slots and bookings.
  3. GET /v1/bookings returns 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 opaque next_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.
  4. Responses carry X-Contract-Version: 0.
  5. 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.
  6. 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.