# Versioning

URL: /code/api/guides/versioning · Id: `page:code/api/guides/versioning`

> The api.sb contract is version 1; the package major names it, additive changes reach it at once, and a breaking change ships as a new major.

The [api.sb](/code/platform/api-sb) contract is version 1. [openapi.json](https://startupbuilder.dev/openapi.json) states it as `info.version`, and every release of `startup-builder@1` calls it.

## Where the version lives
No URL carries the platform version, and no flag selects one. Code pins it by pinning the package major.

| [Interface](/business/nouns/interface) | Pinned by |
| --- | --- |
| API | `https://api.sb/{namespace}` serves version 1, as openapi.json describes it |
| SDK | The package major: `startup-builder@1` |
| CLI | The same package: `npx startup-builder@1` |
| MCP | `https://api.sb/mcp` serves the tools of version 1 |

```bash
npm install startup-builder@1
```

## What counts as breaking
A breaking change is any change that can make correct code fail.

| Breaking | Additive |
| --- | --- |
| Removing or renaming a route, field, [Verb](/business/nouns/verb), [Event](/business/nouns/event), error type or header | A new route, [Noun](/business/nouns/noun), Verb, Event or error type |
| Changing a field's type, unit or meaning | A new field in a response |
| Making an optional input required | A new optional input |
| Narrowing an input's accepted values | A new value in a response field's set |
| Changing a status code, a default [Mode](/business/nouns/mode) or a page-size default | A new response header |

Additive changes reach version 1 as they ship. Clients ignore fields they do not know and handle values they have not seen, so additive changes never break them.

## A breaking change is a new major
A breaking change ships only as the next major: a new `info.version` and a new major of `startup-builder`. Code on `startup-builder@1` keeps calling version 1.

Inside the newest version, a replaced form is deleted, not deprecated: no warnings, no sunset dates, no second way to do one thing.

## A Startup's own API
A [Live](/business/lifecycle/states/live) [Startup](/business/nouns/startup)'s own Nouns and Verbs carry their own version, which its [Customers](/business/nouns/customer)' code relies on. Each [Tenant](/business/nouns/tenant)'s keys answer at the Tenant's `apiVersion`, and a path can name a version after the namespace:

```text
https://api.sb/transcribe.fm/v3/transcripts
```

[Tenant.pin](/business/nouns/tenant/pin) moves a Tenant's keys to another version once a call with its test key passes there. Each [Watch](/business/nouns/watch) keeps the version current when it was created. [Compatibility](/code/builders/software/compatibility) explains how a Startup versions its own API.

## Upgrading
The [Changelog](/changelog) states the current contract and logs each change to it. To take a new major, install it where the `test` key runs, run the tests, then deploy with the `live` key.

## Next
- [The response envelope](/code/api/guides/envelope): the shape version 1 serves.
- [Compatibility](/code/builders/software/compatibility): a Live Startup's own versions.
- [SDK](/code/sdk): the package that names the version.