Skip to main content

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​

FileWhat it is
openapi.jsonThe 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.jsonThe JSON Schema of one workflow result, constellation.item/v2: what a workflow run delivers to connectors and what GET /predictions answers
telemetry.protoThe 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.jsonThe tools the MCP server offers, with their inputs
VERSIONThe contract's version
CHANGELOG.mdWhat each contract version added or removed
DEPRECATIONS.mdWhat 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:

WhatVersionWhere
The contractcontract-vX.Y.Z, such as contract-v1.5.1A release of the API's repository, pinned by the connectors' contract.lock
The connectors repository: CLI, SDKs, bridges, plugins and imagesOne tag, vX.Y.Z, for everything it shipsDownloads
The fleet agentagent-vX.Y.ZReleased 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​

  1. 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.
  2. It keeps working until that version. It is removed only in a major contract version.
  3. 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.verb and 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 whose verb you do not know (today swap and reroute) is one to skip, never to guess at: in a bridge, return false from act().
  • An unknown action_status means held. Only approved may be acted on. Any other value, known or not, is held, like pending. 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 its decision_id in every run that sends it; a new approval of the same action gets a new one. Remember what you acted on by decision_id, falling back to entity.id|verb|to on 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.

ReleaseContractFleet agentYamcsPythonNodeGo
v0.7.1contract-v1.6.0agent-v0.1.05.14.0, 5.13.73.11 or newer18 or newer for the client, 22.6 or newer for the TypeScript bridge scaffold1.22 or newer
v0.7.0contract-v1.5.1agent-v0.1.05.14.0, 5.13.73.11 or newer18 or newer for the client, 22.6 or newer for the TypeScript bridge scaffold1.22 or newer

The other systems the connectors are tested with are listed in Connectors.