Platform API

Versioning

How the /v1 path, the Refabric-Version header and deprecation notices keep your integration working while the API changes.

Three layers

Layer	Example	Changes when
Major version in the path	`/v1`	a change so wide it affects the whole API (rare; announced long in advance)
Dated version header	`Refabric-Version: 2026-09-29`	a small breaking change to shared behaviour (headers, error shapes, envelopes)
Task name	`image.glam` → `image.glam.v2`	a breaking change to one task's inputs or outputs

What is breaking

Breaking (never done without a new version):

removing or renaming an endpoint, field, header or task;
adding a required input field, or making an optional one required;
removing an accepted input value or narrowing a limit;
changing the type or meaning of a field;
changing an error code for the same situation;
changing authentication or signature format.

Not breaking (can happen any day — write your client to tolerate it):

adding endpoints, tasks, optional input fields, response fields, headers;
adding values to output enums (job statuses, error types, codes) — see Conventions;
adding input values or relaxing a limit;
rewording message texts and documentation;
changing the order of object keys, or the length of opaque ids and cursors.

`Refabric-Version`

Refabric-Version: 2026-09-29

The current version is 2026-09-29; send it to pin it.
A date names a snapshot of shared behaviour. Without the header you get the version pinned to your account (by default, the version current when your first key was created).
Responses echo the version used in Refabric-Version.
Each dated change is listed in the changelog with the migration step.

Deprecation and sunset

A task that is going away is first deprecated: it keeps working exactly as before, and you are told in two places.

The catalogue. Its entry in GET /v1/tasks and GET /v1/tasks/{name} carries "status": "deprecated". Nothing else in the entry changes, and an entry without status is current.
The changelog. The same day, the changelog lists it on a Deprecated: line with its replacement (usually the next version of its name, image.glam → image.glam.v2) and a Migration: step. A task is never marked deprecated without that entry.
An e-mail. Once a week, the owner of every API key that started a deprecated task in the last days gets one e-mail naming those tasks and keys, until the calls stop or the task is removed.

Then:

Removal is a Breaking Removed: entry in the changelog; after it the task is no longer in GET /v1/tasks, and every call naming it (GET /v1/tasks/{name}, /estimate, a submit) answers 410 task_removed — not 404, so a client can tell "gone" from "misspelt".

Deprecations are announced in the catalogue and the changelog. Check the catalogue:

for task in s.get(f"{API}/tasks").json()["items"]:
    if task.get("status") == "deprecated":
        log.warning("Refabric task %s is deprecated — see the changelog", task["name"])