assets

Update an asset

Edits the user-editable metadata for a single asset — description, GPS coordinates, and original capture datetime. Only fields included in the request body are changed; others are left untouched. Passing null for a field removes a previously-set value; the effective response may still contain a value from another metadata source. latitude and longitude must be set together (both written or both cleared).

Setting or clearing GPS coordinates schedules an asynchronous refresh of derived location names.

For editing multiple assets in one round trip, prefer bulk_update_assets.

patch/api/assets/{asset_id}

Path parameters

asset_idstring required

Asset ID (with asset_ prefix) of the asset to update.

Request body

descriptionstring nullable

User-set description for the asset. Pass null to remove a previously-set value; the effective response may still contain a description from another metadata source. Omit to leave unchanged. Distinct from the AI-generated description field on the response — this writes to metadata.description.

latitudenumber nullable

GPS latitude in decimal degrees, [-90, 90]. Must be set together with longitude. Pass null (along with longitude=null) to remove a previously-set value; omit to leave unchanged.

longitudenumber nullable

GPS longitude in decimal degrees, [-180, 180]. Must be set together with latitude. Pass null (along with latitude=null) to remove a previously-set value; omit to leave unchanged.

original_datetimestring date-time nullable

When the asset was originally captured. Timezone-aware values preserve their UTC offset; timezone-naive values have no offset. Pass null to remove a previously-set value; the effective response may still contain a datetime from another metadata source. Omit to leave unchanged.

Response

Successful Response

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 (an edit rendered by the client), 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. For a current derived version, this ID supplies the path target for replacement or deletion.

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.

Changes

Changed in 10 of the 79 revisions of this API.14715

Aug 8, 2026815e0302a98811See the full diff
- ▲
  response property detail list-of-types was widened by adding types string to media type application/json of response 422
  response-property-list-of-types-widened
- ○
  the response property detail became required for the status 422
  response-property-became-required
Aug 5, 2026e654ac1b09452See the full diff
- ○
  added the required property current_version_id to the response with the 200 status
  response-required-property-added
- ○
  added the required property kind to the response with the 200 status
  response-required-property-added
Aug 5, 2026c3e15c78f2da4See the full diff
- ○
  added the media type application/json for the response with the status 404
  response-media-type-added
- ○
  added the non-success response with the status 401
  response-non-success-status-added
- ○
  added the non-success response with the status 403
  response-non-success-status-added
- ○
  added the non-success response with the status 429
  response-non-success-status-added
Jul 14, 2026075f79c577a21See the full diff
- ○
  added the optional property stack_id to the response with the 200 status
  response-optional-property-added
Jun 11, 20260af8aaa9fea32See the full diff
- ○
  added the optional property faces/anyOf[subschema #1]/items/confidence to the response with the 200 status
  response-optional-property-added
- ○
  added the required property faces/anyOf[subschema #1]/items/source to the response with the 200 status
  response-required-property-added
Jun 4, 20263b5090d0b2a27See the full diff
- ●
  removed the optional property checksum from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property checksum_sha1 from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property device_asset_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property device_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property file_created_at from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property file_modified_at from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property file_size_bytes from the response with the 200 status
  response-optional-property-removed
Jun 1, 20265ecfeaf25dcc132See the full diff
- ▲
  the response property checksum became optional for the status 200
  response-property-became-optional
- ▲
  the response property device_asset_id became optional for the status 200
  response-property-became-optional
- ▲
  the response property device_id became optional for the status 200
  response-property-became-optional
- ▲
  the response property file_created_at became optional for the status 200
  response-property-became-optional
- ▲
  the response property file_modified_at became optional for the status 200
  response-property-became-optional
- ▲
  response property checksum list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property device_asset_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property device_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property faces list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property file_created_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property file_modified_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property file_size_bytes list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property people list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ○
  added the optional property file_data to the response with the 200 status
  response-optional-property-added
- ○
  the file_size_bytes response's property default value 0 was removed for the status 200
  response-property-default-value-removed
May 30, 2026ece9b5bc44991See the full diff
- ○
  added the optional property thumbhash to the response with the 200 status
  response-optional-property-added
May 27, 2026cf97716473921See the full diff
- ○
  added the optional property duration to the response with the 200 status
  response-optional-property-added
May 13, 2026a6ebc2021e6e1See the full diff
- ○
  endpoint added
  endpoint-added

Full history