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 contract is version 1. 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 | Pinned by |
|---|---|
| API | https: 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: serves the tools of version 1 |
npm install startup-builder@1What counts as breaking
A breaking change is any change that can make correct code fail.
| Breaking | Additive |
|---|---|
| Removing or renaming a route, field, Verb, Event, error type or header | A new route, 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 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 Startup's own Nouns and Verbs carry their own version, which its Customers' code relies on. Each Tenant's keys answer at the Tenant's apiVersion, and a path can name a version after the namespace:
https:Tenant.pin moves a Tenant's keys to another version once a call with its test key passes there. Each Watch keeps the version current when it was created. Compatibility explains how a Startup versions its own API.
Upgrading
The 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: the shape version 1 serves.
- Compatibility: a Live Startup's own versions.
- SDK: the package that names the version.