Versioning your API
A Startup's API versions are named majors in the path; each Tenant answers at its own pinned version, and a breaking Change ships only behind a gate.
A Startup's API versions are named majors, v1 and v2, in the path after the host. Each Tenant answers at its own pinned version, and a breaking Change ships only as the next major.
Where the version lives
| Caller | What pins its version |
|---|---|
| A key | Its Tenant's apiVersion, set when the Tenant was created |
| A request | A version in its path, such as https:, overriding the key |
| The SDK | Its major: leaseline@1 calls v1 |
| A Watch | The version current when it was created, for every Event it delivers |
| An Agent over MCP | Its key: tool names and descriptions match that version's reference |
Additive or breaking
Every Change to a live Startup's Nouns and Verbs is classified at review, from its diff.
| Additive: reaches every version at once | Breaking: only as a new major |
|---|---|
| A new Noun, Verb, Event or optional input | A removed or renamed Noun, Verb, property or Event |
| A new property on an output | A new required input, or a narrower type or set of values |
| A new value in a response field's set | A changed meaning, unit or default |
A restyle, a copy edit or a new Page is not an API Change, and never touches the version.
A breaking Change ships behind a gate
A breaking Change merges only as a new version with a gate: a pair of transforms between the two shapes. A v1 request passes down through the gate and its response comes back up, so v1 callers see exactly what they saw before.
SoftwareBuilder writes the gate when the diff is mechanical, such as a rename or a split field. A change of meaning needs a gate written by hand. A breaking Change with no gate is refused with reason breaking_change_unversioned, and the merge waits.
Upgrading
A Customer upgrades on its own schedule. Harbor Residential points a test key at v2, runs its own code, then calls Tenant.pin, which moves its keys once a test call passes there.
curl -X POST https:The Changelog marks what changed in each version, and each version's reference shows the shapes it serves. Compatibility has the gate rules in full.