> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # List an asset's 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`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/assets/{asset_id}/versions openapi: 3.1.0 info: title: Gumnut API description: >- The Gumnut API manages photo and video libraries: upload and organize assets, search by content, group detected faces into people, and curate albums and stacks. Headless clients authenticate by sending either a Gumnut API key (`apikey_...`) or an OAuth access token as a Bearer token in the `Authorization` header. The Gumnut web and mobile apps sign in with a first-party session (Clerk session JWT) instead, which is also the only credential that can manage API keys. contact: name: Gumnut url: https://www.gumnut.ai/contact version: 1.0.0 servers: - url: https://api.gumnut.ai description: Production security: - apiKeyAuth: [] - oauthJwtAuth: [] tags: - name: assets description: >- Photos and videos in a library: upload, list and filter, update metadata, trash and restore. - name: search description: >- Content-based search over a library's assets, with the same filters as asset listing. - name: albums description: User-curated collections of assets. - name: album-assets description: Link records connecting albums to their member assets. - name: stacks description: >- Groups of related shots of the same moment, presented as a single unit with a cover asset. - name: people description: Named people, each built from clustered faces. - name: faces description: Detected faces and their assignment to people. - name: libraries description: Top-level containers that own assets, albums, people, and everything else. - name: events description: Change-event feed for keeping client state in sync. - name: tasks description: Status of background processing tasks. - name: users description: The authenticated user's profile. - name: api-keys description: >- Create and manage Gumnut API keys. Requires a first-party Gumnut app session — API keys and OAuth tokens cannot manage credentials. - name: oauth description: OAuth flow endpoints for obtaining and refreshing access tokens. - name: server description: Service health. paths: /api/assets/{asset_id}/versions: get: tags: - assets summary: List an asset's versions description: >- 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`. operationId: list_asset_versions parameters: - name: asset_id in: path required: true schema: type: string description: Asset ID (with `asset_` prefix) whose versions to list. title: Asset Id description: Asset ID (with `asset_` prefix) whose versions to list. - name: include in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- 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. title: Include description: >- 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. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/AssetVersionResponse' title: Response List Asset Versions '401': description: Missing, invalid, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Rate limit exceeded. Retry after the interval in the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AssetVersionResponse: properties: id: type: string title: Id description: Unique version identifier with 'asset_version_' prefix position: type: integer title: Position description: >- Zero-based index in the chain: 0 is the uploaded original, the highest is the current rendering. kind: type: string title: Kind description: >- What produced this rendering: `original` (the upload), `edit` (a client-baked edit), or `external:`. The namespace is open — treat an unrecognized kind as opaque rather than failing. params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params description: >- 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: type: string title: Mime Type description: MIME type of this rendering's bytes (e.g., 'image/jpeg') width: type: integer title: Width description: Width of this rendering in pixels height: type: integer title: Height description: Height of this rendering in pixels file_size_bytes: type: integer title: File Size Bytes description: Byte size of this rendering's stored bytes. version_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Version Urls description: >- 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. type: object required: - id - position - kind - mime_type - width - height - file_size_bytes title: AssetVersionResponse description: One rendering in an asset's retained version chain. ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AssetVariant: properties: url: type: string title: Url description: URL to fetch this image variant mimetype: type: string title: Mimetype description: MIME type of the served image width: anyOf: - type: integer - type: 'null' title: Width description: Target width in pixels (null if unknown) type: object required: - url - mimetype title: AssetVariant description: A single image variant with its URL, MIME type, and target width. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: apiKeyAuth: type: http scheme: bearer description: >- Gumnut API key (`apikey_...`) sent as a Bearer token in the `Authorization` header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it. oauthJwtAuth: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT obtained from the OAuth token exchange, sent as a Bearer token in the `Authorization` header. ````