API, schema and SDK versions
Which versions to pin for the route, payload format and client package, and what to check before you upgrade an integration.
Build an integration identity record from the stable HTTP route, exact direction-specific schemas, client-language package version, and any Paper edition you use. Changing one does not change the others.
Keep that record around the existing agent and Kit workflow: the agent retains context and final acceptance, while the Kit prepares permitted requests and connects the approved interface. Version identity does not grant access or make a returned result semantically correct.
Record the integration before changing it
For each operation you use, record the exact client package version, HTTP method and path, request schema, response schema, and representative synthetic success and failure fixtures. Keep the dependency lockfile and the API description used to build the integration with that record.
Retain existing job, batch, quote, and artifact references separately from the client installation. Preserve the original idempotency key and request body for an uncertain submission. Installing a new package is not a reason to submit existing work again.
Keep each identity separate
| Version or edition | What it identifies | Concrete example |
|---|---|---|
| HTTP API | The stable route and method your client calls | POST /v1/jobs |
| Request schema | The fields and validation rules for the request direction | LiveBoundedLithiJobV1, carrying contract_id: "LithiJobV1" and schema_version: "lithi-job.v1" |
| Response schema | The fields and validation rules for the response direction | JobProjection or ResultProjection |
| SDK package | The client-language package release | TypeScript or Go client package version recorded by that package |
| API description format | The format used to describe the API, not a Compute endpoint | OpenAPI 3.1.1 |
| Paper edition | An explanatory publication edition, separate from wire compatibility | The edition named by the Paper itself |
The /v1 route is stable independently of the request and response schema names. Use the method and
path declared for the operation; do not derive URLs from type names. A Paper edition explains a system
or method and does not create a runtime route or universal runtime version.
Pin the client and validate the payload
Record the exact package version in your dependency lockfile. Keep the API description used to build the integration alongside your contract fixtures, and record the operation's request and response schema references separately.
For job submission, LiveBoundedLithiJobV1 identifies the public request wrapper, while
LithiJobV1 and lithi-job.v1 are the exact payload identifiers. The HTTP success response wraps a
direction-specific job projection in data; it is not another copy of the submitted job. Read the
schema for each direction rather than expecting one version field on every response.
A request can also bind a capability release, model, policy or output schema. Preserve those identifiers where the operation defines them. Do not add a generic workflow.version field to a strict request that does not declare it.
Check compatibility before a deliberate upgrade
Compatibility depends on the sender and receiver, not only the name of the change. The TypeScript client validates exact request and response keys. An older decoder can reject a newly added response field even when a newer schema calls that field optional.
| Change | Compatibility check |
|---|---|
| Add an optional request field | Confirm the server accepts it before the client starts sending it. |
| Add an optional response field | Confirm every supported reader accepts it; a strict older reader can reject it. |
| Add an enum member | Check exhaustive switches and validators. Preserve the member's exact case. |
| Remove a field or require a new one | Update the affected sender, reader and fixtures together. |
| Change nullability, units or a numeric bound | Check serialization and validation, including boundary values. Missing and null are different. |
| Change state or error behavior | Recheck completion, retries, cancellation and recovery. |
| Add a separate operation | Existing callers need no new method merely to keep using their current operation; verify shared behavior is unchanged. |
A type cast, ignored validation error or renamed schema label is not a migration. Preserve unknown-field rejection where the contract requires it.
Upgrade deliberately
First exercise the new client with its controlled or injected transport. Compare its method, path,
request bytes and decoded response with the version you use now. Python's synchronous LithiClient
and TypeScript's promise-based LithiComputeClient expose different calling conventions; do not
copy method names, argument shapes or response handling from one into the other. Include invalid
fields, typed errors and a lost-response recovery, not only success.
Check strict decoding with an extra response field, a missing required field, an invalid enum,
omitted versus null, and a typed HTTP error. Check request byte limits as well as item counts. A
synthetic transport proves only the exercised client behavior and does not establish live access.
Recover uncertain work
Keep the original job handle and idempotency key during recovery. Installing a new client does not authorize a new submission, change an accepted quote or erase work already accepted. Read the existing job before deliberately starting replacement work.
Pinning a package does not freeze server availability, permissions, price or capacity. Check those conditions through the operation's normal access and quote flow.
Check retirement notices explicitly
Use an applicable release notice for any support window or retirement date. A schema suffix, package version or source-change date does not establish that two versions remain callable together. Do not assume an overlap period or an automatic upgrade path.
Before switching the application, use the client guides to confirm the selected caller's methods and recovery behavior, then use request and response schemas to confirm the wire contracts.