API versioning

Where a version appears#

Two different kinds of version live side by side and confusing them is the usual mistake. The *product* version moves when Connect ships. The *protocol* version is the specification revision an interface implements and moves when that specification does. A card can carry a new product version and the same protocolVersion: 1.0.0 for a long time, and nothing is wrong.

How compatibility is actually kept#

Not by a version selector, which nothing here has, but by accepting more than one revision where a specification has moved. The MCP endpoint implements 2026-07-28 and also answers clients speaking 2025-11-25, 2025-06-18 and 2025-03-26: an initialize from one of those gets a normal result with the agreed version echoed back, and later requests are accepted without the per-request metadata the current revision expects. Refusing them would have meant the connector directories of the day could not reach Connect at all.

The same instinct applies to the A2A card. An earlier draft of the specification put it at /.well-known/agent.json; that path still answers with the same document plus a Link header naming the current path as canonical, so an agent built against the draft finds Connect instead of concluding it does not speak A2A.

And an unsupported revision is refused loudly rather than guessed at: a version string the MCP endpoint does not know produces an error whose data.supported array lists the four it does. A client can recover automatically from that.

The descriptions are generated, not maintained#

openapi.yaml, the Arazzo workflows, the AsyncAPI document and the agent card are all produced by the documentation build from the same capability registry the pages come from. Nobody edits them by hand, and the next build overwrites them. That is what stops a description drifting from behaviour — the classic failure where an API stays the same and its document quietly stops matching.

It also means the description's version follows the build. If you have cached a copy, compare info.version and the generated date rather than diffing YAML, and regenerate your client when either moves.

What not to pin to#

• A search result's position. Ranking depends on the index, which rebuilds when the corpus does. Pin to a url or an id.
• The wording of a message. Error messages are prose for a log; branch on error.code instead, with a default branch for a code you do not know.
• The shape of an id. Ids are stable and opaque. The letters are not a classification — kind is a field you can read.
• The absence of a field. Treat unknown fields as ignorable rather than as an error, so an additive change to a response does not break your parser.
• A page's prose. It is regenerated. Cache on the page's updated date, which exists for exactly this.

Questions#

Related#

• The OpenAPI description
• The Connect MCP server
• The Connect Agent Card
• The changelog and its feed
• Stable identifiers
• OpenAPI