---
title: "Replace the current derived asset version"
method: POST
path: "/api/assets/{asset_id}/versions/{version_id}/replace"
tags: ["assets"]
---

# Replace the current derived asset version

`POST /api/assets/{asset_id}/versions/{version_id}/replace`

Uploads a fully rendered image and replaces the version named in the path. That version must still be the current non-original version; the server infers its parent. Exact duplicates store nothing. Metadata is copied from the original, so retained bytes may differ from uploaded bytes.

## Path parameters

- `asset_id` string, required — Asset ID (with `asset_` prefix) whose version to replace.
- `version_id` string, required — Version ID (with `asset_version_` prefix) to replace. It must be the asset's current non-original version.

## Query parameters

- `include` string[], nullable — Optional response expansion. The single accepted value is `variants`: without it each row's `version_urls` carries only its lean thumbnail rung; with it, every rung plus the signed exact-byte `original`. Accepts multiple `include=` query params or a single comma-delimited value. Unknown values return 422.

## Response `200`

The upload duplicates the current version (same `kind`, `params`, and bytes); that version is returned and nothing new is stored.

- AssetVersionResponse — One rendering in an asset's retained version chain.
  - `id` string, required — Unique version identifier with 'asset_version_' prefix
  - `position` integer, required — Zero-based index in the chain: 0 is the uploaded original, the highest is the current rendering.
  - `kind` string, required — What produced this rendering: `original` (the upload), `edit` (an edit rendered by the client), or `external:<service>`. The namespace is open — treat an unrecognized kind as opaque rather than failing.
  - `params` object, nullable — How this rendering was produced (e.g. an edit recipe). Opaque to the server; the schema is defined by whichever producer sets `kind`. `null` only for the original.
  - `mime_type` string, required — MIME type of this rendering's bytes (e.g., 'image/jpeg')
  - `width` integer, required — Width of this rendering in pixels
  - `height` integer, required — Height of this rendering in pixels
  - `file_size_bytes` integer, required — Byte size of this rendering's stored bytes.
  - `checksum` string, nullable, required — Base64-encoded SHA-256 hash of this rendering's stored bytes, for comparing a locally computed hash against the chain (e.g. when reconciling an ambiguous create failure). Not unique: identical bytes may legitimately appear at different positions or on other assets. Transitionally null for roots written during the column's rollout window, until a follow-up backfill lands.
  - `version_urls` object, nullable — URLs for this rendering, shaped like an asset's `asset_urls`: the lean `thumbnail`/`thumbnail_image` rung by default; `include=variants` adds the remaining rungs and `original`, this rendering's exact stored bytes.

## Other responses

- `201` — Successful Response
- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `409` — The requested append or replacement does not match the asset's current state. Refetch the asset before choosing the next action.
- `422` — The multipart body, version metadata, or uploaded image is invalid.
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.
- `502` — Transient storage or metadata-finalization error. Retryable: retry the upload after the interval in the `Retry-After` header. The detail carries a stable `error_code` (`"transient_storage_error"` or `"metadata_finalization_error"`) plus `asset_id` and `part_number` keys (possibly null).
- `507` — Retaining the new version would exceed the account or library storage cap. Not retryable until space is freed or the cap is raised.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/revisions/2c3aca3a6e6d/schema)