# How to tie SDK release versions to API versions

> Pin one API version per SDK release, send it as a header that callers can override, record the document it came from, and bump the SDK by what its surface lost.

Source: https://voxgig.com/howto/tie-sdk-release-versions-to-api-versions

- Audience: library-maintainer
- Level: advanced
- Languages: typescript, python, go
- Verified: 2026-11-22
- Published: 2026-11-21

## Short answer

In sdkgen, add one line to .sdk/model/project.aontu that copies the document's info.version into the client's default headers, so every target sends it on every request. Callers override it with the headers constructor option or per call. Check the pin against .sdk/def/api.json before each release, and bump the SDK by what its generated surface changed, not by how far the API version moved.

---
## You will need

Node 22 or later, an SDK generated from an OpenAPI document, and an API that reads its version
from a request header. The sample's document, `api.json`, declares a `Bookshelf-Version` header
parameter whose default is its own `info.version`, `2026-11-01`. The sample runs offline against
files committed from one generation, listed in its `README.md`.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) | A Go client that should carry a copy of its source document inside the binary | No default for the header, so a request editor you write sends the pin | You need the version in a package manifest, not in code |
| [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) | A Python client whose header defaults should come straight from the document | A date `info.version` becomes the package version, which PEP 440 refuses | You ship more than Python from one document |
| [sdkgen](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | One model generates TypeScript, Python and Go, and each should send one pin | An overlay line that fails on a project's first generate, and a case-sensitive header merge | One language, where a generator that reads the default needs no overlay |
| [Speakeasy](https://www.speakeasy.com/docs/sdks/manage/versioning) | You want the SDK bump computed on every generation without a script of your own | An account, and a bump read from `info.version` and checksums, never from what the operations changed | `info.version` is a date, where every change reads as a patch |
| [Stripe SDKs](https://docs.stripe.com/sdks/set-version) | A model to copy: each release pins the API version current when it shipped | The Java, Go and .NET SDKs cannot target any version but the one their release pins | Your callers need to choose a version per client in every language |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

Stripe shows the shape this page builds: one pinned version per SDK release, which its Ruby SDK,
for one, lets a caller override with a `stripe_version` client option. `openapi-python-client`
reads the pin from the document with no configuration and breaks the Python package version doing
it. oapi-codegen embeds a copy of the document but sends no version until you add a request
editor. Speakeasy's CLI [asks for an account](https://www.speakeasy.com/docs/sdks/create-client-sdks)
before it generates anything.

Stainless is left out of the table: on May 18, 2026 it [closed new signups and projects](https://www.stainless.com/blog/stainless-is-joining-anthropic/)
while it winds down its SDK generator.

## Pin the document's version in the project overlay

sdkgen writes each target's default headers from `main.kit.config.headers`, and the model language
can read another path's value. One line in the project overlay, which regeneration never rewrites,
copies `info.version` into those headers:

```aontu title="generated/sdkgen/2026-11-01/model/project.aontu"
# The API version this release pins, read from the document.
main: kit: config: headers: "bookshelf-version": $.main.kit.info.version
```

Run `npm run generate` inside `.sdk/`. `pin-record.mjs` reads the committed generation and lists
every file that records the API version or the document, then fails if any target disagrees with
the document:

```bash
node pin-record.mjs generated/sdkgen/2026-11-01 api.json
```

```text output
generated/sdkgen/2026-11-01
  def/api.json                 info.version 2026-11-01, sha256 a4cf69edfd20, a byte copy of the document
  model/api/api-info.aontu     version 2026-11-01
  log/generated.jsonl          1 record, 283 files by component, carries no API version or hash
  ts/src/Config.ts             bookshelf-version 2026-11-01
  py/bookshelf_sdk/config.py   bookshelf-version 2026-11-01
  go/core/config.go            bookshelf-version 2026-11-01
  ts/package.json              release 0.0.1
  py/pyproject.toml            release 0.0.1
  go/VERSION                   release 0.0.1
  pin matches the document
```

The document travels with the project as `.sdk/def/api.json`, and the model keeps its version.
The generation log maps each written file to the component that wrote it, so it says what was
generated and not from which document. The manifests carry the SDK's own release number, which is
a separate decision. Record the document's hash in your release notes, because none of these files
holds it.

## Send the pin, and let a caller choose another

The client sends the pin as a default header. The model's
[option schema](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) gives every
client a `headers` option, and a header parameter declared in the document becomes a per-call key,
here `bookshelf_version`. `demo.mjs` makes five calls against a stand-in API on `127.0.0.1` and
prints what it recorded:

```bash
node demo.mjs
```

```text output
default client, Book().list()                GET /v1/books       2026-11-01
default client, Author().load()              GET /v1/authors/a1  2026-11-01
headers option, Book().list()                GET /v1/books       2026-10-01
per-call bookshelf_version, Author().load()  GET /v1/authors/a1  2026-12-01
default client, direct()                     GET /v1/authors/a1  2026-11-01
```

The constructor option pins a whole client, the per-call key moves one request, and `direct()` for
paths outside the model still carries the default. Without the overlay line, the default headers in
`Config.ts` hold `content-type` alone, as `records/unpinned-config-current.txt` shows, so the
client sends no `Bookshelf-Version`. The document's default reaches the model as an example, not as
a value to send. sdkgen's [API versioning design note](https://github.com/voxgig/sdkgen/blob/main/docs/design/api-versioning.md)
agrees: the generator's own code never reads `info.version`, and the header the note proposes
would be off by default. The note is a discussion draft and says that none of it is implemented.

## Bump the SDK by its surface, not by the date

The API's next version, `2026-12-01`, adds `lifespan` to one schema. `bump.mjs` compares the models
of the two generations entity by entity and prints what three rules make of it:

```bash
node bump.mjs generated/sdkgen/2026-11-01/model/sdk.json generated/sdkgen/2026-12-01/model/sdk.json
```

```text output
info.version 2026-11-01 -> 2026-12-01, pinned header 2026-11-01 -> 2026-12-01
  author   field lifespan added
  book     unchanged
bump by rule
  major on every API version  major
  info.version as SemVer      patch (info.version is not SemVer, checksum changed)
  generated surface           minor (author)
```

A pin protects callers from a server change they did not ask for, at the price of a release for
each version they want. A major for every API version pushes the callers who never use `author`
through an upgrade.
Speakeasy's documented rule compares `info.version` as a semantic version and falls back to a document checksum,
so a dated version reads as a patch whatever it added.[^1] The surface rule names the entity and the
level. Release a major only when the surface loses, retypes, or newly requires something. Release
one also when the API itself calls the version you move the pin to breaking, as
[Stripe](https://docs.stripe.com/api/versioning) does twice a year.[^2] A caller who needs a breaking version sooner sets it per call or per client
inside a minor.

## Pin the same version in the two other generators

`openapi-python-client` writes the header's document default into each function signature, so the
generated client sends `2026-11-01` with no configuration and takes `bookshelf_version=` per call.
`record.sh` ran it against a stand-in:

```text title="records/openapi-python-client-run.txt"
GET /v1/authors/a1 bookshelf-version=2026-11-01
GET /v1/authors/a1 bookshelf-version=2026-12-01
```

Its README says that unset, `package_version_override` makes the client "use the version of the
OpenAPI spec". A date is not a [PEP 440](https://peps.python.org/pep-0440/) version, so the default
project does not build:[^3]

```text title="records/pep440.txt"
openapi-python-client/default/pyproject.toml: version 2026-11-01, invalid under PEP 440
openapi-python-client/pinned/pyproject.toml: version 1.4.0, valid, 1.4.0
uv build of default/: exit 2
InvalidVersionError: Invalid PEP 440 version: '2026-11-01'
```

oapi-codegen generates the header as an optional pointer in each operation's parameter struct and sends
nothing by default. Its `spec` output, `embedded-spec: true` in a configuration file, compiles the
document into the client, and `main.go` reads `info.version` from it in a request editor passed
with [`WithRequestEditorFn`](https://github.com/oapi-codegen/oapi-codegen#on-the-client):

```text title="records/oapi-codegen-run.txt"
embedded info.version: 2026-11-01
embedded bytes equal api.json: false
embedded JSON equals api.json: false
GET /books operationId: embedded ListBooks, api.json listBooks
GET /v1/authors/a1 bookshelf-version=""
GET /v1/authors/a1 bookshelf-version="2026-11-01"
GET /v1/authors/a1 bookshelf-version="2026-12-01"
```

The embedded copy is a re-serialization with operation ids rewritten, so hash your file, not the
copy.

## Check it worked

The suite covers the pin in all three targets, the overrides, and a target pinned to the wrong
version. It also checks the unpinned build, the next document, a removed field, a changed type,
a field or parameter made required, a moved path, and every recorded run.

```bash
node --test tie.test.mjs
```

```text output
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 320.300398
```

## When it goes wrong

The first generate stops. On a fresh scaffold, `model/api/api-info.aontu` is empty until a
generate fills it, and the line's reference stops the build. Generate once without the line, then
add it. `@voxgig/sdkgen` 4.45.0 does the same:

```text title="records/first-generate-current.txt"
sdkgen 4.44.3, apidef 8.32.4: npm run generate exit 1
ERROR: model                  run-build            build
  path: ["main","kit","config","headers","bookshelf-version"]
  why: "mapval_no_gen"
```

The server receives two versions. The SDK's option merge matches keys exactly, so
`Bookshelf-Version` sits beside `bookshelf-version`, and `fetch`'s `Headers` joins the two values
with a comma. [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.3) lets a sender
produce that joined form only for a field defined as a list. Write the header name in lower case.

```text title="records/header-case.txt"
sdkgen 4.45.0, apidef 8.33.1
  headers: { 'bookshelf-version': '2026-10-01' }  sent 2026-10-01
  headers: { 'Bookshelf-Version': '2026-10-01' }  sent 2026-10-01, 2026-11-01
sdkgen 4.44.3, apidef 8.32.4, the committed build
  headers: { 'bookshelf-version': '2026-10-01' }  sent 2026-10-01
  headers: { 'Bookshelf-Version': '2026-10-01' }  sent 2026-10-01, 2026-11-01
```

The pin moves without a release note. A regenerate from a fetched document picks up its new
`info.version` in the same run. Run `pin-record.mjs` in CI against the document you meant to
release.

## When not to do this

Do not pin in the SDK if the API has one version and no plan for a second. A header nobody reads
is a release step with nothing behind it.

Skip the sdkgen overlay line when Python is your only client. `openapi-python-client` sends the
document's default without it, at the price of one `package_version_override` line. For a Go
client that must report its document's `info.version` at run time, oapi-codegen's embedded spec
carries it with no overlay, as a re-serialized copy whose hash is not your file's.

Do not send the pin from a browser until the API's CORS policy allows the header. A custom header
makes the browser send a preflight first, which is the design note's reason to keep its header off
by default.

Do not take Speakeasy's bump for a dated API. With `info.version` as a date, every document change
reads as a patch, a removal included.

Do not move the default pin inside a patch. A different version is different behavior on the
server, even when the generated code does not change.

## Related how-tos

- [Pin an API version from a client](/howto/pin-an-api-version-from-a-client)

- [Decide if a regenerated SDK is a minor or major release](/howto/regenerated-sdk-minor-or-major-release)

- [Choose lockstep or independent versions across your SDKs](/howto/lockstep-or-independent-versions-across-sdk-languages)

- [Verify an SDK, CLI and MCP server share one model version](/howto/verify-surfaces-share-one-model-version)

- [Release six SDK packages from one commit](/howto/release-six-sdk-packages-from-one-commit)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3,
`@voxgig/apidef` 8.32.4, `openapi-python-client` 0.30.0 and oapi-codegen v2.8.2. Every output block
is what the command preceding it printed, and each titled record is a file `generate.sh` or
`record.sh` wrote. `@voxgig/sdkgen` 4.45.0 with `@voxgig/apidef` 8.33.1 was scaffolded the same
way and behaved the same in both failures. Speakeasy was not run; its bump rule is read from its
versioning page, and Stripe's practice from its own documentation. The design note was found by
listing `docs/design` in the sdkgen repository.

[^1]: Speakeasy's [versioning page](https://www.speakeasy.com/docs/sdks/manage/versioning) is
direct about the limit. It says Speakeasy does not analyze the content of the OpenAPI document,
such as added or removed operations, and evaluates only `info.version` and the overall checksum.
The same page says Speakeasy turns a detected major into a minor for every Go SDK, because a Go
major changes the import path, unless the bump is forced.

[^2]: Stripe's [versioning page](https://docs.stripe.com/api/versioning) dates the scheme from
`2024-09-30.acacia`: monthly versions with no breaking changes, and twice a year a major release
that opens with one. The page names Basil as its example of a major and gives `2026-11-18.endive`
as the current version. All three names are plants.

[^3]: [PEP 440](https://peps.python.org/pep-0440/) does allow dates, written as release segments
separated by dots, and its example scheme runs 2012.4, 2012.7, 2012.10. A date in the API's own
spelling, with hyphens, is not among the forms it lists. The generated project names poetry-core as
its build backend, which is the part that said so.