Skip to main content

Postman collection

Download the collection: constellation-os.postman_collection.json

The collection covers the full API surface with one folder per endpoint family: Health (all four probes), Topology, Telemetry (a POST with a sample record array), and Predictions (cached and live). Request descriptions carry the real limits and error codes, so the collection doubles as inline reference while you explore.

Import​

  1. In Postman: File, then Import, then drop in constellation-os.postman_collection.json (or paste the URL above if your docs site is reachable from Postman).
  2. Open the collection's Variables tab and set apiKey to your tenant API key.
  3. Send GET /health first; it needs no key and confirms connectivity. Then send GET /topology to confirm your key works.

Auth​

Collection-level auth sends x-api-key: {{apiKey}} on every request. The Health folder overrides this with No Auth because /health* endpoints are open; everything else inherits the collection auth.

Treat the key like a credential: set it as a secret type variable, or better, keep it in a Postman environment or vault rather than in the shared collection, so exporting or sharing the collection never leaks it.

Environments​

baseUrl defaults to production. The collection embeds all three base URLs as documented variables:

VariableValue
prodBaseUrlhttps://api.constellation.space
devBaseUrlhttps://dev.api.constellation.space
sandboxBaseUrlhttps://sandbox.api.constellation.space

Two ways to switch:

  • Quick: edit the baseUrl collection variable to one of the values above.
  • Clean: create three Postman environments (prod, dev, sandbox), each defining baseUrl and apiKey. Environment variables shadow collection variables, so the environment picker becomes your environment switch, and each environment can hold its own key. Keys are environment-specific; a prod key does not work against sandbox.

What to expect while exploring​

  • POST /telemetry returns 202 with write_id, accepted_count, rejected_count, and rejected_indices. Send more than 1000 records to see the 413 batch_too_large envelope.
  • GET /predictions with live=true returns the provenance-carrying InferencePayload; without it you get the cached PredictionSet.
  • Hammering Send trips the real rate limits (per-IP 30/min, per-tenant 60/min): a 429 rate_limited response with retry_after_seconds and a Retry-After header.
  • Repeated requests with a wrong key trigger the auth lockout: 5 failures within 300 seconds lock your IP for 900 seconds (429 auth_lockout). Double-check the key before retrying in a loop.