Skip to main content

OpenAPI document

Download the document: constellation-os.yaml

This is a contract-true OpenAPI 3.1 description of the ConstellationOS tenant API. It is hand-maintained against the implementation; the API does not serve an OpenAPI document publicly, so this file is the machine-readable source of truth for tooling.

What it encodes:

  • All three servers: prod, dev, and sandbox.
  • The ApiKeyAuth security scheme (x-api-key header), applied globally and explicitly disabled on the open /health* endpoints.
  • Every real path: GET /health, GET /health/{subsystem} with the telemetry | topology | predictions enum, POST /telemetry, GET /topology, and GET /predictions.
  • The real request and response schemas: TelemetryRecord (non-empty measurement, date-time time, string tags, number-or-string fields), the 202 TelemetryWriteAck with nullable rejected_indices, Topology with its entity projection, and the PredictionSet or InferencePayload oneOf on /predictions, including the full provenance schema.
  • The real limits as schema constraints: 1000-item telemetry arrays, 100-item link_ids, freshness_seconds between 1 and 604800.
  • The real error envelope: a required error code plus the documented optional fields (retry_after_seconds, field, max, received, max_bytes, received_bytes, upstream, reason), with per-status examples for auth_lockout, rate_limited, batch_too_large, request_too_large, too_many_link_ids, invalid_input, and telemetry_unavailable.

Code generation​

The document works with standard OpenAPI tooling. With openapi-generator:

# TypeScript (fetch-based)
openapi-generator-cli generate \
  -i ./constellation-os.yaml \
  -g typescript-fetch \
  -o ./generated/constellation-ts

# Python
openapi-generator-cli generate \
  -i ./constellation-os.yaml \
  -g python \
  -o ./generated/constellation-py

Generated clients give you types and transport, but not the operational behaviors the API rewards: automatic telemetry batching at 1000 records, the client-side link_ids cap, and Retry-After aware retries. The vendorable TypeScript and Python clients implement those on top of the same contract; a common pattern is generating types from this document and keeping the vendored client for transport.

Validation and drift​

Lint it with any 3.1-aware validator, for example:

npx @redocly/cli lint constellation-os.yaml

If you observe the live API disagreeing with this document, the API is the authority; please report the discrepancy so the document can be corrected.