Skip to main content
GET
Get an asset

Path Parameters

asset_id
string
required

Asset ID (with asset_ prefix) to fetch.

Query Parameters

include
string[] | null

Opt-in expansion fields. Supported values: metadata (camera/EXIF/GPS and location names), faces, people, metrics (ML quality scores), file_data (a group token populating the nested file_data object with the file/provenance scalars device_asset_id, device_id, file_created_at, file_modified_at, checksum, checksum_sha1, file_size_bytes), and variants (the non-thumbnail asset_urls size variants; without it asset_urls carries only its lean rung — thumbnail, or thumbnail_image for a video with an extracted still, or original for a still-less video — so callers that render non-thumbnail variants must pass it). Accepts multiple include= query params or a single comma-delimited value (e.g. include=faces,people). Unknown values return 422. When omitted, only the lean core is returned (id, mime_type, local_datetime, dimensions, description, thumbhash, asset_urls) and each data field above is null/absent until you request it.

Response

Successful Response

Represents a photo or video asset with metadata and access URLs.

id
string
required

Unique asset identifier with 'asset_' prefix

mime_type
string
required

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

original_file_name
string
required

Original filename when the asset was uploaded

local_datetime
string<date-time>
required

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

created_at
string<date-time>
required

When this asset record was created in the database

updated_at
string<date-time>
required

When this asset record was last updated

file_data
FileDataResponse · object | null

File/provenance scalars (device IDs, file timestamps, checksums, file size) grouped into one nested object. null when not requested via include=file_data; when present, every field is populated (checksum_sha1 may still be null for legacy rows).

metadata
MetadataResponse · object | null

Asset metadata — camera/EXIF fields, GPS, and location names. null when not requested via include=metadata.

metrics
Metrics · object | null

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

asset_urls
Asset Urls · object | null

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 (, 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.

description
string | null

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).

thumbhash
string | null

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.

faces
FaceResponse · object[] | null

All faces detected in this asset. null when not requested via include=faces; [] when requested but the asset has no faces.

people
PersonResponse · object[] | null

All unique people identified in this asset (deduplicated from faces). null when not requested via include=people; [] when requested but none are identified.

width
integer
default:0

Width of the asset in pixels

height
integer
default:0

Height of the asset in pixels

duration
number | null

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

trashed_at
string<date-time> | null

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_id
string | null

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.