SDKs
Versioning
Every build is recorded against the spec version that produced it. When you publish, Octri propagates that version into the generated package manifests, so the version on npm and the version in your OpenAPI document agree.
The spec is the source of truth
The generated manifests (package.json, pyproject.toml, go.mod) are overwritten on every build. A version edited there is lost the next time you generate. Change info.version in the spec instead.
info:
title: Acme API
version: 2.4.0What counts as breaking
Your SDK's version communicates to callers what upgrading will cost them. A spec change that looks small can be a breaking change in a generated client:
| Spec change | Effect on the SDK |
|---|---|
| Add an optional parameter | Additive, unless Argument style is positional |
| Add a required parameter | Breaking. Every existing call site is now wrong |
| Rename a field | Breaking in typed languages, silent in untyped ones |
| Remove an endpoint | Breaking. The method disappears |
| Change a response type | Breaking in typed languages |
| Add an endpoint | Additive |
Change an operationId | Breaking. The method is renamed |
Method names derive from operationId. Tidying one in the spec silently renames the method your users call. If the name is wrong, override it per endpoint in Studio instead: the override keeps the public name stable while the spec changes underneath.
Deprecating instead of removing
Removing an operation breaks callers at compile time. Deprecating it warns them at compile time and keeps their code working.
Mark it deprecated in Studio with a message pointing at the replacement, ship that for a release or two, then remove it.
Versions and the docs site
Docs versions and SDK versions are related but separate: each published spec is a docs version readers can switch between, and each build records the spec that produced it. A reader on docs v1 can still see v1's endpoints while your SDK ships v2. See Docs versioning.
Version history
Your plan sets how many SDK versions Octri retains. Older artifacts age out; anything already published to a registry stays there, since Octri doesn't unpublish.