# Versioning your API

URL: /products/api/versions · Id: `page:products/api/versions`

> 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](/business/nouns/startup)'s API versions are named majors, `v1` and `v2`, in the path after the host. Each [Tenant](/business/nouns/tenant) answers at its own pinned version, and a breaking [Change](/business/nouns/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://api.leaseline.app/v2/leases`, overriding the key |
| The SDK | Its major: `leaseline@1` calls `v1` |
| A [Watch](/business/nouns/watch) | The version current when it was created, for every [Event](/business/nouns/event) it delivers |
| An [Agent](/business/nouns/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](/business/nouns/noun) and [Verbs](/business/nouns/verb) 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](/business/nouns/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](/code/builders/software) 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](/business/nouns/customer) upgrades on its own schedule. Harbor Residential points a `test` key at `v2`, runs its own code, then calls [`Tenant.pin`](/business/nouns/tenant/pin), which moves its keys once a test call passes there.

```bash
curl -X POST https://api.leaseline.app/tenants/ten_WshoCmQ26J/pin \
  -H "Authorization: Bearer $LEASELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"v2"}'
```

The [Changelog](/code/systems/changelog) marks what changed in each version, and each version's reference shows the shapes it serves. [Compatibility](/code/builders/software/compatibility) has the gate rules in full.