> ## 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. # Append an asset version > Uploads a fully rendered image — with all edits already applied to its pixels — above the original version. An append is accepted only while the original is current; replace the current derived version through its replacement endpoint instead. Exact duplicates store nothing. Metadata is copied from the original, so retained bytes may differ from uploaded bytes. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json post /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: post: tags: - assets summary: Append an asset version description: >- Uploads a fully rendered image — with all edits already applied to its pixels — above the original version. An append is accepted only while the original is current; replace the current derived version through its replacement endpoint instead. Exact duplicates store nothing. Metadata is copied from the original, so retained bytes may differ from uploaded bytes. operationId: append_asset_version parameters: - name: asset_id in: path required: true schema: type: string description: Asset ID (with `asset_` prefix) to add the version to. title: Asset Id description: Asset ID (with `asset_` prefix) to add the version to. - 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. requestBody: required: true content: multipart/form-data: schema: type: object required: - file - kind - params properties: file: type: string format: binary description: >- JPEG or PNG bytes with all edits and orientation already applied to the pixels, at most 100 MiB. The metadata-finalized file must also remain within that limit. The part's `Content-Type` declares the expected format; the format detected from the bytes is authoritative, and a concrete declared type that disagrees with it returns 422. kind: type: string maxLength: 64 description: >- What produced this rendering: `edit` for an edit rendered by the client, or `external:` for an external producer. `original` is reserved for the uploaded position-0 version. params: type: string maxLength: 16384 description: >- JSON object describing how the rendering was produced (e.g. an edit recipe), serialized as a string. Opaque to the server; the schema is defined by whichever producer sets `kind`. Malformed JSON, a non-object, or an over-large object returns 422. responses: '200': description: >- The upload duplicates the current version (same `kind`, `params`, and bytes); that version is returned and nothing new is stored. content: application/json: schema: $ref: '#/components/schemas/AssetVersionResponse' '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AssetVersionResponse' '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' '409': description: >- The requested append or replacement does not match the asset's current state. Refetch the asset before choosing the next action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: The multipart body, version metadata, or uploaded image is invalid. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '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' '502': description: >- 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': description: >- Retaining the new version would exceed the account or library storage cap. Not retryable until space is freed or the cap is raised. 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` (an edit rendered by the client), 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. checksum: anyOf: - type: string - type: 'null' title: Checksum description: >- 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: 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 - checksum 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 UnprocessableEntityResponse: title: UnprocessableEntityResponse type: object properties: detail: title: Detail description: >- A semantic validation message or structured request-validation errors. oneOf: - type: string description: Human-readable semantic validation message. - type: array items: $ref: '#/components/schemas/ValidationError' description: Structured request-validation errors. required: - detail 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. ````