Health

The health surface is four unauthenticated GET endpoints. They exist so availability monitoring never depends on tenant credentials: a prober with no API key can still answer "is the platform up, and which subsystem is degraded?"

Endpoints

Endpoint	Status behavior	What it proves
GET /health	Always 200 while the process serves traffic	The API is reachable and the service is alive.
GET /health/telemetry	200 healthy, 503 degraded	The telemetry ingest path, verified by a real downstream ping.
GET /health/topology	200 healthy, 503 degraded	The topology read path, verified by a real downstream ping.
GET /health/predictions	200 healthy, 503 degraded	The prediction serving path, verified by a real downstream ping.

The subsystem endpoints are not static flags; each one actually pings its dependency on every call.

Response shape

{
  "status": "ok",
  "checks": {
    "influx": { "ok": true, "detail": "ping 12ms" }
  }
}

Field	Description
status	Overall verdict, ok when healthy.
checks	Named dependency checks, each with ok and a human-readable detail.

Treat a response as healthy only when the HTTP status is 200, status is ok, and no entry in checks has ok: false. A 200 whose body is not this JSON shape usually means the URL is not actually the Constellation API (a proxy or captive portal answered instead).

Example

curl -sS https://api.constellation.space/health
curl -sS -o /dev/null -w "%{http_code}\n" https://api.constellation.space/health/predictions

Monitoring usage

• Uptime probes should hit /health and alert on non-200 or timeout. No key, no lockout risk, no tenant coupling.
• Subsystem dashboards should probe the three subsystem endpoints and page on sustained 503, which maps directly to "ingest is down" versus "reads are down" versus "predictions are down".
• Rate budget: health endpoints still count against the per-IP limit of 30 requests/minute (rate limiting runs before auth). Four endpoints polled once a minute uses 4 of 30; do not fan out probes tighter than that from a single IP. See Errors and limits.

Key validity: the authed /topology probe

Health endpoints deliberately know nothing about your key or tenant. To verify the credential and the tenant data plane, the standard probe is an authenticated topology read with a small window:

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

Interpretation:

Outcome	Meaning
200 with your tenant_key	Key valid, tenant routed, data plane serving. Non-empty entities also proves telemetry flowed within the window.
401 auth_failed	Key is wrong or not provisioned in this environment. Alert; do not retry (lockout risk).
403 / 404 / 503	Tenant disabled, unknown, or its data plane unavailable. See Authentication.

Run the key probe at a much lower cadence than the health probes (it spends tenant rate budget and, on failure, feeds the auth lockout counter). The console's connection test chains exactly these stages; see Integration bundle and the runnable versions in Monitor the platform and Connection smoke test.