---
summary: The states a version moves through, and who moves it.
title: Version lifecycle
path: concepts/version-lifecycle
status: published
---

# 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 |

```
create ──▶ uploading ──(you mark it)──▶ ready ──▶ deprecated ──▶ deleted
```

### `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

```python
client.versions.update("poolnoodle", "noodletron", "1.0.0", status="ready")
```

```bash
curl -X PATCH \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"status": "ready"}' \
  "$BASE/api/v1/namespaces/poolnoodle/models/noodletron/versions/1.0.0"
```

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:

```json
{"detail": "Version is not available (current: uploading)"}
```

That is the signal that the publish step has not happened — not that the
upload failed.

## Deprecating and deleting

```python
client.versions.update("poolnoodle", "noodletron", "1.0.0", status="deprecated")
client.versions.delete("poolnoodle", "noodletron", "1.0.0")
```

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](/docs/scaiatlas/guides/uploading-a-model) — the full publish path.
- [Resource model](/docs/scaiatlas/concepts/resource-model) — where versions sit.
