API overview

The Constellation platform API is a small, tenant-scoped HTTP surface for fleet operations: push telemetry in, read the latest fleet state back out, and fetch SNR predictions for your links. It is designed for server-to-server integrations such as gateway agents, mission scripts, and CI jobs.

What the API covers

Surface	Method and path	Auth	Purpose
Health	GET /health, GET /health/telemetry, GET /health/topology, GET /health/predictions	None	Liveness and per-subsystem readiness. See Health.
Topology	GET /topology	x-api-key	Latest-known state per entity from your telemetry. See Topology.
Telemetry	POST /telemetry	x-api-key	Batch ingest of time-series records. See Telemetry.
Predictions	GET /predictions	x-api-key	Cached or live SNR predictions per link. See Predictions.

A separate /rules* surface exists for platform operators and requires an operator Cognito identity token. It is not part of the customer API and is not documented here.

There is no pagination, no webhook delivery, and no streaming endpoint anywhere on this API. Integrations are built on polling; see Integration patterns.

Tenancy

Every request is scoped to exactly one tenant, and that tenant is derived from the validated API key, never from the hostname you call. Each tenant gets a dedicated data plane (its own time-series database instance and encryption key), so your telemetry and predictions are physically isolated from other tenants. See Authentication.

Base URLs

Environment	Base URL	Notes
Production	https://api.constellation.space	Manual promotion gate; the public production API.
Stage	https://stage.api.constellation.space	Pre-production promotion target.
Development	https://dev.api.constellation.space	Continuous deploy on every merge.
Sandbox	https://sandbox.api.constellation.space	Separate account outside the promotion pipeline; hosts the live SNR inference endpoint.
GovCloud dev	https://api.dev.gov.constellation.space	GovCloud environment family.
Dedicated tenant	https://<codename>.api.constellation.space	Dedicated single-tenant stacks in their own AWS account. Precedent: the whitney tenant at warpware.api.constellation.space.

API keys are provisioned per environment. A key issued for dev does not work on prod. Even on a dedicated custom domain, the tenant is still resolved from the key, not the domain.

Server-to-server first, CORS by allowlist

Call this API from backend code. Browser calls only work from origins on the per-environment CORS allowlist:

• Commercial environments and dedicated tenants currently allow https://sos.constellation.space.
• Sandbox additionally allows https://constellation.space.
• When no origins are configured for an environment, CORS is entirely off and browsers block cross-origin calls.

The allowlist accepts the x-api-key header where enabled, but shipping a tenant API key to a browser is almost never the right design. Keep keys server-side.

Quickstart

First confirm the platform is up. /health needs no credentials:

curl -sS https://api.constellation.space/health

{
  "status": "ok",
  "checks": {}
}

Then make your first authenticated call. GET /topology doubles as a key-validity probe:

curl -sS \
  -H "x-api-key: $CONSTELLATION_API_TOKEN" \
  "https://api.constellation.space/topology?freshness_seconds=900"

{
  "as_of_utc": "2026-07-09T14:32:00Z",
  "tenant_key": "acme-sat",
  "entities": [
    {
      "measurement": "satellite",
      "entity_id": "SAT-0012",
      "observed_at": "2026-07-09T14:31:42Z",
      "tags": { "node_id": "SAT-0012", "node_type": "satellite" },
      "fields": { "lat": 47.61, "lon": -122.33, "altitude_km": 550.2, "utilization": 0.42 }
    }
  ]
}

A 200 with your tenant_key means the key is valid and scoped correctly. An empty entities array means the key works but nothing has reported telemetry inside the freshness window yet; start with Ingest telemetry.

Where next

• Authentication: the x-api-key model, lockout behavior, key handling.
• Errors and limits: every error shape, rate limits, body caps, retry rules.
• Integration bundle: the console-issued config.toml, fleet agent, and staged connection test.
• Examples: runnable clients in TypeScript, Python, Go, and cURL.