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.

Subsystem endpoints check dependencies with timeouts and cached results to limit probe load. A successful probe does not verify a particular account's data or prove a forecast can be produced.

Response shape

{
  "status": "ok",
  "checks": {
    "telemetry_store_wired": { "ok": true, "detail": null },
    "telemetry_store_ping": { "ok": true, "detail": null }
  }
}

Field	Description
status	Overall verdict, ok when healthy.
checks	Named dependency checks, each with ok and an optional detail.

When present, detail is a coarse token ("timeout", "connection_error", "skipped:no_tenant_registered", "endpoint_status:InService"), not free-form text. Root GET /health reports resolver, router, telemetry_store, and prediction_store; the subsystem endpoints report their own downstream checks (for example telemetry_store_wired and telemetry_store_ping above).

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: the /health and /health/* endpoints are exempt from rate limiting, so an uptime prober can poll them without spending per-IP or per-tenant budget and without lockout risk. Reserve the rate budget for authenticated calls. See Errors and limits.

Key validity: the authed /topology probe

Health checks do not verify your API key. Confirm authenticated access with a topology read:

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

Interpretation:

Outcome	Meaning
200	Authenticated read succeeded. Check sample times and simulation metadata before treating entities as evidence of ingestion.
401 auth_failed	Key is wrong or not provisioned in this environment. Alert; do not retry (lockout risk).
403 / 503	Tenant disabled (tenant_disabled) or its data plane unavailable (tenant_unavailable). See Authentication.

Run authenticated checks less frequently than health checks. They consume request budget and rejected credentials can trigger lockout. Use the connection smoke test and follow retry guidance.

Next: Errors and limits — the full error envelope and the rate limits the probes must respect.