Webhooks and SDKs
Constellation pushes results to your own HTTPS endpoint as signed webhooks. To call the API, use the Python or TypeScript SDK, the constellation CLI, or any HTTP client.
Webhooks
A webhook destination POSTs JSON to an endpoint you run: each workflow run whose graph has a destination output naming it, and the latest link SNR forecasts your live keys read by link_ids on GET /predictions. Reads by at or as_of_utc are not sent. Setup, the request and a signature check in Python are in Send forecasts to a webhook.
| Header | Carries |
|---|---|
Constellation-Event | workflow for a run, delivery for served forecasts, check for a connection test |
Constellation-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> of "<t>.<raw body>", keyed with your signing secret |
Idempotency-Key | The same on every delivery of the same request: a run's <run_id>:<destination_id>:<part>, or the delivery's id for served forecasts. A connection test carries none |
The body's items are as GET /predictions returns them, in the shared response shape. A large run arrives as several workflow requests, one per part, tied together by workflow.run_id.
To receive them safely:
- Check the signature over the raw body, and refuse a timestamp more than a few minutes old.
- Drop a request whose
Idempotency-Keyyou have already applied. A delivery that failed is sent again, so the same request can arrive twice. - Answer with a 2xx within 10 seconds.
| Your endpoint answers | What happens |
|---|---|
| 2xx | Delivered |
| 408, 425, 429 or 5xx, or nothing within 10 seconds | Sent again, then set aside after repeated failures |
| 400, 409, 413 or 422 | Not sent again; the reason is recorded and the destination keeps its status |
| Any other 4xx, or a redirect | Not sent again; the destination shows Needs attention with the reason |
Test runs and scenario runs send no webhooks. Webhooks need Operator; see Results out.
Building on Constellation
| What | Is | Use it for |
|---|---|---|
| The HTTP API | REST and JSON, with your key in x-api-key | Everything: curl, requests, fetch, any language. Start with the API overview |
| The SDKs | constellation-space for Python and @constellationspace/client for TypeScript: an API client, a reader of workflow results (constellation_space.results, client.results()) and a base class for bridges | Your own scripts, services and connectors |
The constellation CLI | One binary for Linux and macOS | Logging in with your key, watching workflow results (constellation results tail), running a mock API, scaffolding and checking a bridge, verifying a download |
| The fleet agent | A Linux service with the constellation-agent command and a local socket | Publishing telemetry from your hosts. Its socket protocol takes records only; it reads nothing back |
| Connectors | Bridges for Yamcs, Open MCT, OpenC3 COSMOS and Anduril Lattice, and a scaffold for your own: Build a connector in Python, TypeScript or Go, checked against a mock API | Putting workflow results in your mission control system (MCS) |
| The MCP server | Tools over the Model Context Protocol | Letting an AI agent read and act on your fleet |
The SDKs and the CLI ship with each release of the connectors, on the public connectors GitHub releases, one vX.Y.Z tag for everything. The SDKs are also on PyPI (constellation-space) and npm (@constellationspace/client) from the first public release on. Downloads lists every release file and image, and how to verify and mirror them.
The public contract
Everything you can build on is published as a contract: the OpenAPI document of every route you call with your own key, the JSON Schema of a workflow result, the telemetry record, and the MCP tools. It is generated from the API's own code and released as a versioned release of the API repository, contract-vX.Y.Z, a tarball with its .sha256. Contract versions follow semantic versioning: a minor version only adds, and a major version removes only what was announced as deprecated. The SDKs are built on it (the TypeScript API types are generated from it, and the Python result types are tested against it), and each connectors release pins the contract version it was built against. Contract and versioning says what stays stable, how deprecations are announced, and which versions work together.
The workflow results endpoints keep their original name, /predictions/feed. The endpoint pages are Telemetry, Topology, Topology config and Predictions.