How-to › Describe your API

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.

Audience
Library maintainer
Level
advanced
Topic
Version and retire APIs
Languages
TypeScript, Python and Go
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
oapi-codegenA Go client that should carry a copy of its source document inside the binaryNo default for the header, so a request editor you write sends the pinYou need the version in a package manifest, not in code
openapi-python-clientA Python client whose header defaults should come straight from the documentA date info.version becomes the package version, which PEP 440 refusesYou ship more than Python from one document
sdkgenOne model generates TypeScript, Python and Go, and each should send one pinAn overlay line that fails on a project’s first generate, and a case-sensitive header mergeOne language, where a generator that reads the default needs no overlay
SpeakeasyYou want the SDK bump computed on every generation without a script of your ownAn account, and a bump read from info.version and checksums, never from what the operations changedinfo.version is a date, where every change reads as a patch
Stripe SDKsA model to copy: each release pins the API version current when it shippedThe Java, Go and .NET SDKs cannot target any version but the one their release pinsYour 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.

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

  1. 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.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. ↩︎ Back to text

  2. 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 gives 2026-11-18.endive as the current version. All three names are plants. ↩︎ Back to text

  3. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.