> ## Documentation Index
>
> Fetch the complete documentation index at: https://lithi.ai/llms.txt
>
> Use this file to discover all available pages before exploring further.

---
title: Versioning
description: >-
  Compute tracks six version lines separately. How to pin one, what counts as a breaking change, how
  overlap and retirement work, and why a contract version is not an endpoint version.
route: /docs/compute/reference/versioning
page_id: docs-compute-reference-versioning
page_type: reference
content_layer: technical reference
surface_profile: technical_reference
audience: 'Integrators pinning versions and planning upgrades against Compute'
voice: D
reader_question: 'Which versions exist, which do I pin, and what will break me?'
primary_action: Pin an exact workflow version in production
source_locale: en-US
source_status: APPROVED
source_version: docs-compute-reference-versioning-en-us-2026-09-05-v1
last_updated: '2026-09-05'
robots: index
claim_registry_pinned: true
claim_registry_resync: "npm run governed:tsx -- scripts/build-compute-public-claim-registry.ts --write"
---

## Six version lines, tracked separately

Six things carry a version, and they move independently. Treating them as one number is the most common upgrade mistake.

| Version line | What it versions | Where you read it |
| --- | --- | --- |
| API | The operation surface and its paths | Developer settings, and the API description |
| Contract | The response envelope and payload shapes | The contract release on every response |
| Workflow | One workflow's behavior, parameters and output | `workflow.version` on your request |
| Profile | Your team's defaults for policy, quality, output and limits | The profile record, versioned and retired explicitly |
| Adapter | A compatibility level and its conformance matrix | The adapter's published matrix |
| Client | One released client library | That client's page |

## How to pin a version

`workflow.version` accepts an exact version, such as `eval.semantic_grade.v1`. It also accepts `current-compatible`, which follows the current compatible release.

Pin exactly in production. Use `current-compatible` while you explore, and only where a changed output would not reach anyone.

Profiles are versioned by a deliberate act. You create a version, and you retire an old one; neither happens as a side effect of another change.

## A contract version is not an endpoint version

The contract release on your response describes the payload shape. The API version describes the operation surface. They move on separate schedules.

A response can move to a new contract release with no path changing at all. A new path can appear with no contract release moving. So record both, and never infer one from the other in a compatibility check.

## What counts as a breaking change

Unknown fields are rejected rather than dropped, so "additive" is not automatically safe for you.

Breaking:

- Removing a field you send or read.
- Narrowing the values a field accepts.
- Changing what a typed state means, or which states are terminal.
- Requiring a field you do not currently send.

Not breaking:

- Adding an optional field you may ignore.
- Adding an operation you do not call.
- Publishing a new workflow version alongside the one you pin.

The last one is the reason to pin exactly. A new workflow version cannot reach your pinned requests.

## Overlap and retirement

A new version is published alongside the version it replaces, so both are callable during the overlap.

Retirement is an explicit, published act, not a silent stop. The dates of an overlap window are published on the descriptor for that version and repeated in the change record. Do not infer a window from a release date, and do not assume one is open-ended.

While an overlap is open, run the new version against a small input and compare results before you move production traffic.

## Adapter compatibility levels

Four named levels exist: `import_compatible`, `wire_subset_compatible`, `official_sdk_compatible` and `full_endpoint_compatible`.

A level is a name plus a published conformance matrix. The matrix states the supported upstream version, and the field, lifecycle, error and limit coverage behind the claim.

A compatibility claim without that matrix is not a compatibility claim. Read the matrix for the exact upstream version you use, then see [how a change is recorded](/docs/compute/reference/changelog) before you upgrade.