v72

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-076576348.0 KB

assets

Upload a new asset

Uploads a new asset (image or video) and its metadata as multipart form data, returning the created asset with 201. Uploads are deduplicated per library by the file's SHA-256 checksum: re-uploading a file whose bytes already exist in the target library stores nothing and returns the existing asset with 200. Storage caps are checked before the duplicate lookup, so an upload is refused with 507 whenever the account or the target library is already at its storage cap — even when the bytes would have deduplicated to an existing asset. A transient upstream storage error returns 502 — retryable after the Retry-After interval. When library_id is omitted and no default library can be chosen (the account has multiple live libraries), the request is refused with 400. Image metadata is extracted before the response returns; the rest of processing (thumbnails, search indexing, face detection, and video metadata extraction) continues asynchronously after the response.

post/api/assets

Response

The file already exists in the target library (matched by SHA-256 checksum); the existing asset is returned and nothing new is stored.

idstring required

Unique asset identifier with 'asset_' prefix

mime_typestring required

MIME type of the current rendering (e.g., 'image/jpeg', 'video/mp4').

original_file_namestring required

Filename the asset was uploaded under.

local_datetimestring date-time required

When the photo/video was taken, in the device's local timezone

created_atstring date-time required

When this asset record was created in the database

updated_atstring date-time required

When this asset record was last updated

metricsobject nullable

ML-generated quality scores and other metrics. null when not requested via include=metrics.

asset_urlsobject nullable

Named asset variants. Images: 'original', 'thumbnail', 'small', 'preview', 'fullsize'. Videos: 'original', plus 'thumbnail_image', 'small_image', 'preview_image', 'fullsize_image' pointing at the extracted still. 'original' is served with a Content-Disposition attachment header (signed 'dl' filename param) so a top-level navigation saves it to disk, while inline subresource loads (<video>, fetch) still render it. Variant URLs are stable: a derived variant may briefly 404 until its artifact is generated, then serve from the same URL.

descriptionstring nullable

AI-generated description of the asset's content, quality, and composition. null means description generation has not yet run; empty string means the model refused to describe the asset. Distinct from metadata.description (camera-embedded EXIF metadata).

thumbhashstring nullable

Base64-encoded ThumbHash placeholder (~28 chars). Clients decode with the thumbhash library (JS / Swift / Kotlin) to render an instant blurred preview before the CDN thumbnail arrives. null while generation is pending.

kindstring required

What produced the current rendering: original (the upload), edit (a client-baked edit), or external:<service>. The namespace is open — derive edited-ness as kind != "original".

current_version_idstring required

ID (asset_version_ prefix) of the current version, which the top-level rendering fields describe. Pass it as the expected current version on version writes so a racing write is rejected.

widthinteger

Width of the current rendering in pixels.

heightinteger

Height of the current rendering in pixels.

durationnumber nullable

Video length in seconds. null for images and for videos whose duration has not been extracted yet.

trashed_atstring date-time nullable

When this asset was moved to trash (ISO 8601, UTC). null for live assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window.

stack_idstring nullable

ID of the stack this asset belongs to (asset_stack_ prefix), or null when the asset is not part of a stack. Group assets by this value to collapse a stack into a single tile; the stack's own cover and member count are not carried on the asset. Distinct from metadata.auto_stack_id, which is the camera's in-EXIF MakerNotes:AutoStackID string — this is the server-assigned foreign key to the asset's stack.