Contract and versioning
The contract is the part of Constellation you can build on: the routes you call with your own key, the shape of a workflow result, the telemetry record, and the tools an AI agent sees. It is generated from the API's own code, so it cannot drift from what the API serves, and every SDK and bridge is a thin layer over it.
What the contract holds
| File | What it is |
|---|---|
openapi.json | The OpenAPI document for every route a customer calls with their own key: account, assets, topology, telemetry, predictions, workflows, actions, connectors and workflow results (the /predictions/feed endpoints, which keep their original name) |
workflow-result.schema.json | The JSON Schema of one workflow result, constellation.item/v2: what a workflow run delivers to connectors and what GET /predictions answers |
telemetry.proto | The telemetry record, package constellation.ingest.v2, that the fleet agent and gRPC TelemetryIngest.Write send. POST /telemetry takes the same record as JSON |
mcp-tools.json | The tools the MCP server offers, with their inputs |
VERSION | The contract's version |
CHANGELOG.md | What each contract version added or removed |
DEPRECATIONS.md | What a future version removes, the version that removes it, and what to use instead |
The API's repository publishes the contract as a versioned release, contract-vX.Y.Z: a tarball, contract-X.Y.Z.tar.gz, and its .sha256. The connectors repository commits one release unpacked, as readable files under contract/, and pins its version and each file's SHA-256 in contract.lock; make contract checks the files against it with no network, and the generated client code is built from them, so that code is never committed. Moving the connectors to a new contract is make contract-update VERSION=X.Y.Z, which unpacks the published tarball into contract/ and rewrites contract.lock. Compatibility lists the contract each connectors release pins.
Versions
Three things are versioned, each on its own:
| What | Version | Where |
|---|---|---|
| The contract | contract-vX.Y.Z, such as contract-v1.5.1 | A release of the API's repository, pinned by the connectors' contract.lock |
| The connectors repository: CLI, SDKs, bridges, plugins and images | One tag, vX.Y.Z, for everything it ships | Downloads |
| The fleet agent | agent-vX.Y.Z | Released from the API's repository; see fleet agent |
All three follow semantic versioning. For the contract, a minor version only adds: a route, an optional field, an enum value, a tool. A major version removes, and only what DEPRECATIONS.md announced. Every change to the API is checked against the contract before it: a pull request against its base, and each release against the last published contract. It fails if it removes something a client can rely on, unless DEPRECATIONS.md lists it, and a release also needs the version to have reached its removal version. A contract that changed is always published under a new version.
While the connectors repository is 0.x, a breaking change is a new minor version, and every 0.x release is a pre-release. See Connectors: compatibility and versions for what counts as breaking for a bridge.
Deprecation policy
- A route, field, enum value, MCP tool or model family that will go is listed in
DEPRECATIONS.md, with the contract version that removes it and what to use instead, in the release that deprecates it. - It keeps working until that version. It is removed only in a major contract version.
- A new workflow result schema is served alongside the old one for at least one connector minor release, and the changelog names the release that drops the old one. Upgrade your bridges before then.
Today an old name of the snr model family and a few renamed routes are deprecated; both still answer. See Aliases.
Forward compatibility
Write clients so a newer API never breaks them:
- Ignore fields you do not know. Objects in the contract are open: a minor version adds fields.
- Accept string values you do not know.
severity,entity.type,action.verband the other string fields list their known values, and a minor version adds more. Handle the ones you know and pass over the rest; never reject an item for one. An approved action whoseverbyou do not know (todayswapandreroute) is one to skip, never to guess at: in a bridge, return false fromact(). - An unknown
action_statusmeans held. Onlyapprovedmay be acted on. Any other value, known or not, is held, likepending. Never treat an item with a status you do not know as a plain forecast or as an instruction. - Check the item schema. Each result carries
constellation.schema. A bridge skips, and logs, a record in a shape it was not built for instead of guessing. The SDKs and the official bridges do. - Act once per decision. A result whose action is held for approval carries
action_id, the same for that action (verb, entity and target, and on a link the start of its span) in every run, and once decided,decision_id, one per decision. A standing approval keeps itsdecision_idin every run that sends it; a new approval of the same action gets a new one. Remember what you acted on bydecision_id, falling back toentity.id|verb|toon a result without one, so a standing approval is acted on once and a re-approval is acted on again. The SDKs keep these keys beside the cursor and drop each one 7 days after its action expires.
constellation conformance checks the last three for any bridge. Receive results is the whole loop over plain HTTP, its field tables generated from the contract.
Compatibility
What each release of the connectors repository is built and tested against. The same table is under Compatibility in the connectors repository's README.
| Release | Contract | Fleet agent | Yamcs | Python | Node | Go |
|---|---|---|---|---|---|---|
| v0.7.1 | contract-v1.6.0 | agent-v0.1.0 | 5.14.0, 5.13.7 | 3.11 or newer | 18 or newer for the client, 22.6 or newer for the TypeScript bridge scaffold | 1.22 or newer |
| v0.7.0 | contract-v1.5.1 | agent-v0.1.0 | 5.14.0, 5.13.7 | 3.11 or newer | 18 or newer for the client, 22.6 or newer for the TypeScript bridge scaffold | 1.22 or newer |
The other systems the connectors are tested with are listed in Connectors.
Related
- API overview: endpoints and access
- Workflow results protocol: workflow results in detail
- SDKs: the Python and TypeScript packages built on the contract