Pipelines & versioning

Two things are versioned independently:

The API contract — the shape of requests and responses — is versioned in the path (/v1).
The pipeline — the models, prompts, thresholds and reference data that produce results — is versioned as releases.

API version

Within /v1 we only make additive, backwards-compatible changes: new endpoints, new optional fields, new enum values where documented as open (for example match.reason), new error codes and new nutrient keys. Write clients that ignore unknown fields and treat unknown codes generically. Breaking changes would ship as /v2, with a long overlap.

Pipeline releases

A release is a calendar-named, immutable combination of an engine build and a profile: the vision model and its settings, prompt versions, matching thresholds, feature switches such as the image cross-check, and the food-composition reference data.

Term	Example	Meaning
Release	`2026-10.1`	One exact release
Family	`2026-10`	The newest generally available release in that family
`latest`	`latest`	The newest generally available release of any family (opt-in)
Profile hash	`sha256:3f…`	Content hash of the profile; equal hashes mean identical configuration

Pinning

Your organization has a default release, pinned when it is created. You can change it in the console's Settings.
A request can choose another with "pipeline": "2026-10.1" (or a family, or latest).
The resolved release and profile hash are pinned on the workflow at creation and used for every later stage. A manual-mode analysis confirmed three days later is processed by the same pipeline as its identification, even if a newer release shipped in between.

Every response carries the release in the Opis-Pipeline-Release header, and resources record it:

JSON

"pipeline": {
  "requested": "2026-10",
  "release": "2026-10.1",
  "profile_hash": "sha256:9b1d…",
  "reference_data": "refdata-2026.10.0"
}

GET /v1/pipelines lists releases with their status, dates and change notes. An unknown or retired pipeline value returns 400 pipeline_not_found.

What is guaranteed

Within a release, the configuration is fixed. Results are stable given identical model responses — but AI models are not perfectly deterministic, so two runs on the same photo can differ slightly. We report the release and profile hash rather than promise bit-for-bit equality.
Across releases, results may change (that is the point of a new release). Each release is benchmarked before it becomes generally available, and its notes describe what changed.

Lifecycle

preview → GA → deprecated → retired

Preview releases are opt-in for evaluation and may change.
A GA release is deprecated with at least 90 days' notice, and retired no sooner than 180 days after its successor reaches GA.
Requests on a deprecated release still succeed, with Deprecation and Sunset headers (and a Link to the notes). Your owners receive the pipeline.deprecated webhook.
A release is never retired while workflows pinned to it are still waiting for confirmation.
At most two releases run side by side.

Upgrading

Read the release notes for the new release.
Send a sample of real traffic with "pipeline": "<new release>" (test mode is not representative here — it returns fixtures) and compare results.
Change your organization's default release in the console when you are satisfied.