API Versioning & Deprecation Policy

VIUCraft favors stability. This page explains how the API is versioned, what counts as a breaking change, and how deprecations are announced — so you can integrate once and trust it keeps working.

The version

The current contract version is 2025-01 — a dated version. You can read it at runtime:

1. The version field of the OpenAPI spec (info.version).
2. The api_version field returned by GET /api/v1/whoami and GET /api/capabilities.

A dated version (rather than v1.2.3) makes it obvious how old a contract is and lets us ship additive improvements continuously without churning a number.

Stable surfaces

These are stable and safe to hard-code:

1. URL prefixes — /api/ (management), /api/v1/ (versioned services), and the root delivery paths (/, /upload).
2. The delivery URL grammar — see Delivery & Transform URL Grammar.
3. image_id — a permanent handle; never recycled. See Upload Response Reference.
4. The error envelope — { error: { code, message, status, docs_url, request_id, ... } }.

What is (and isn't) a breaking change

Additive — may ship at any time, not breaking:

1. New endpoints, new optional request parameters, new response fields.
2. New image operations, new error code values, new enum members.

Write clients that ignore unknown response fields so additions never surprise you.

Breaking — never shipped in place:

1. Removing or renaming a field, endpoint, or error code.
2. Changing a field's type or an existing parameter's meaning.
3. Tightening validation in a way that rejects previously-valid input.

A breaking change ships under a new dated version and a new path prefix (e.g. a future /api/v2/*); the existing surface keeps working.

Deprecation

When something is slated for removal:

1. It is announced in the changelog — GET /api/changelog (and the docs changelog).
2. It keeps working for at least 6 months after the announcement.
3. Where applicable, responses carry a Deprecation and/or Sunset header during the window.

Recommendations

1. Pin nothing you don't have to; read api_version from whoami/capabilities if you want to assert a minimum.
2. Use the official viucraft SDK — it tracks the contract for you.
3. Subscribe to the changelog (or a webhook) so deprecations reach you before the sunset date.