Version lifecycle
A version moves through states as you publish it. Nothing moves it for you.
The registry never promotes a version by itself: it is created in uploading,
it stays there while you push bytes, and it becomes downloadable only when you
say so.
That last step is the one people miss. A version whose files all uploaded cleanly is still not downloadable until you mark it.
The states#
| Status | What it means | Downloadable |
|---|---|---|
uploading |
Created. Files are being pushed, or were pushed and it has not been published yet. | No |
processing |
Reserved for server-side work. Nothing sets it today. | No |
ready |
Published. | Yes |
deprecated |
Discouraged for new work, still served. | Yes |
deleted |
Soft-deleted. | No |
1 | |
ready and available are the same state#
The stored value is available; responses rename it to ready. You can send
either when you write — {"status": "ready"} and {"status": "available"}
both land on the same state — and you will always read ready.
This matters if your client reads a status and sends it back, which is a natural thing to do. That works.
failed is read-only#
failed appears in the response enum but is not a state a version can be put
into. Sending it returns 422, naming the reason, rather than failing
halfway through the write.
Marking a version ready#
1 | |
1 2 3 4 | |
The Python SDK's upload session does this for you: complete() uploads every
file and then marks the version ready, so a session that returns normally
leaves a version you can download. If you drive the REST API yourself, the
PATCH is yours to make.
Until you mark it#
GET …/versions/{version}/download returns 400 while the version is
uploading, with the current status in the message:
1 | |
That is the signal that the publish step has not happened — not that the upload failed.
Deprecating and deleting#
1 2 | |
Deprecating means do not start anything new on this version. It keeps
downloading, so anything already pinned to it keeps working; latest stops
offering it. Only deletion stops it serving.
That split is deliberate: whoever publishes a release usually does not know who is pinned to the previous one, so retiring a version is the publisher's decision and stopping the bytes is a separate, later one.
Deleting is a soft delete of the record.
Deleting removes the stored files as well as the record. If an upload was still in flight, its multipart parts are abandoned too, so nothing is left being paid for. The same applies to deleting a variant, and to deleting a whole model, which takes every version with it.
Storage is emptied before the record goes. If storage cannot be reached the
delete fails with 502 and nothing is removed, so a retry finishes the job
rather than leaving files no record points at.
Variant statuses#
Variants have their own, separate set: pending → converting → available,
or failed. These are not renamed — a variant reads available, not ready.
See also#
- Uploading a model — the full publish path.
- Resource model — where versions sit.