Your generated SDK sends no version header, so each call is served under whatever version the API applies by default that week. A support ticket names SDK 1.4.0, but the package cannot say which API document it was built from. When the API changes one endpoint, the SDK goes to 2.0.0 and every caller has to upgrade.
What you get
You will end up with an SDK release that sends one pinned API version, lets a caller choose another, and records the document it came from. This is for you if you publish an SDK for an API that versions by header.
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 | 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 | 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 | 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 | 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 | 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
before it generates anything.
Stainless is left out of the table: on May 18, 2026 it closed new signups and projects 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:
# 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:
node pin-record.mjs generated/sdkgen/2026-11-01 api.json
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 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:
node demo.mjs
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
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:
node bump.mjs generated/sdkgen/2026-11-01/model/sdk.json generated/sdkgen/2026-12-01/model/sdk.json
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 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:
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 version, so the default
project does not build:3
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:
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.
node --test tie.test.mjs
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:
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 lets a sender
produce that joined form only for a field defined as a list. Write the header name in lower case.
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
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.
Footnotes
-
Speakeasy’s versioning page 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.versionand 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. ↩︎ Back to text -
Stripe’s versioning page 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 gives2026-11-18.endiveas the current version. All three names are plants. ↩︎ Back to text -
PEP 440 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. ↩︎ Back to text