---
title: "List an asset's versions"
method: GET
path: "/api/assets/{asset_id}/versions"
tags: ["assets"]
---

# List an asset's versions

`GET /api/assets/{asset_id}/versions`

Returns every retained rendering of one asset, ordered by `position` ascending — the uploaded original first, the current rendering last. Not paginated. Each entry's `version_urls` follows the same `include` semantics as an asset's `asset_urls`: lean `thumbnail` by default, `include=variants` for the remaining rungs and the exact-byte `original`.

## Path parameters

- `asset_id` string, required — Asset ID (with `asset_` prefix) whose versions to list.

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

Successful Response

- AssetVersionResponse[]
  - `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` (a client-baked edit), 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

- `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
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[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/bf08b1e1d8bd/schema)