API version pinning

ISA versions each API surface independently. One surface can sit on /v3 while another is still on /v1; the SDK routes per surface, not globally.

When a new version ships for one surface, you can pin the others to their previous version while you migrate — without forking the SDK.

The version-per-surface model

There is no global "current API version." Each surface has its own version history, and each SDK release pins each surface to one /vN. The pin is the bundled default for that release.

Surfaces evolve at different cadences. For example, prequalify might add a new offer schema while quote stays unchanged. A global version would force every surface to revalidate even though only one changed — per-surface versioning avoids that waste.

BundledApiVersions

Every SDK release exports a constant table mapping each surface to the /vN it targets in that release:

import { BundledApiVersions } from 'isa-sdk';

console.log(BundledApiVersions);
// {
//   prequalify: 'v3',
//   quote: 'v3',
//   datasets: 'v3',
//   reference: 'v3',
//   sessions: 'v1',
//   branding: 'v1',
//   cases: 'v1',
// }

BundledApiVersions tells you what each SDK release targets. Read it directly — don't hard-code version strings.

Per-call resolution

For every call, the SDK resolves the target version as:

apiVersion[surface] ?? BundledApiVersions[surface]

The apiVersion option is a per-surface map. Surfaces you don't list fall through to the bundled default.

When to override

Override during a migration window. ISA shipped prequalify v3; your code already runs on v2 and you want to migrate quote on a separate PR. Pin quote to v2, let prequalify move to the bundled default (which is now v3):

import { Isa } from 'isa-sdk';

const isa = await Isa.withBearer(undefined, undefined, {
  apiVersion: {
    quote: 'v2',                 // everything else uses BundledApiVersions
  },
});

Once you finish migrating quote, delete the pin. The SDK falls back to the bundled default.

What it does NOT do

apiVersion does not change SDK method signatures. Your call sites stay identical.

import { Isa } from 'isa-sdk';
import type { PrequalifyRequest } from 'isa-sdk';

const isa = await Isa.withBearer();
declare const req: PrequalifyRequest;

// Same call site, regardless of which /vN it routes to internally.
await isa.zyins.prequalify(req);

The call site looks the same whether prequalify routes to /v2 or /v3. Versioning is internal — the SDK adapts request and response shapes to match the target /vN. Your code stays on one path; the SDK absorbs the wire-format changes.

apiVersion pins which /vN a surface targets, not which SDK method to call. Breaking changes ship as deprecations, not new method names, so you never need V3 suffixes in your code.