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

## Request

- Base URL: `https://api.gumnut.ai`
- URL: `https://api.gumnut.ai/api/assets/{asset_id}/versions`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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

- `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`: Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it.
- `422`: Validation Error
- `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header.
- `503`: Authentication provider temporarily unavailable. Retry sign-in later.

## Changes

- **2026-10-16** `7c2860d9eb88`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `503`
- **2026-08-08** `815e0302a988`: 1 breaking, 1 info
  - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422`
  - the response property `detail` became required for the status `422`
- **2026-08-07** `e71db45f5d4a`: 1 info
  - added the required property `items/checksum` to the response with the `200` status
- **2026-08-05** `e654ac1b0945`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/assets/:asset_id/versions/get.md)

---

[API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) - [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gumnut-ai/apis/gumnut-api/revisions/4dcbf19e1db8?raw)