Update an asset

curl --request PATCH \
  --url https://api.example.com/api/assets/{asset_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "latitude": 123,
  "longitude": 123,
  "original_datetime": "2023-11-07T05:31:56Z"
}
'

{
  "id": "<string>",
  "mime_type": "<string>",
  "original_file_name": "<string>",
  "local_datetime": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "file_data": {
    "device_asset_id": "<string>",
    "device_id": "<string>",
    "file_created_at": "2023-11-07T05:31:56Z",
    "file_modified_at": "2023-11-07T05:31:56Z",
    "checksum": "<string>",
    "file_size_bytes": 123,
    "checksum_sha1": "<string>"
  },
  "metadata": {
    "asset_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "make": "<string>",
    "model": "<string>",
    "orientation": 123,
    "raw_width": 123,
    "raw_height": 123,
    "modified_datetime": "2023-11-07T05:31:56Z",
    "original_datetime": "2023-11-07T05:31:56Z",
    "digitized_datetime": "2023-11-07T05:31:56Z",
    "lens_model": "<string>",
    "f_number": 123,
    "focal_length": 123,
    "iso": 123,
    "exposure_time": 123,
    "exposure_bias": 123,
    "latitude": 123,
    "longitude": 123,
    "altitude": 123,
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "country_code": "<string>",
    "sublocation": "<string>",
    "place_name": "<string>",
    "timezone": "<string>",
    "display_label": "<string>",
    "description": "<string>",
    "fps": 123,
    "live_photo_cid": "<string>",
    "projection_type": "<string>",
    "auto_stack_id": "<string>",
    "rating": 123
  },
  "metrics": {},
  "asset_urls": {},
  "description": "<string>",
  "thumbhash": "<string>",
  "faces": [
    {
      "id": "<string>",
      "asset_id": "<string>",
      "bounding_box": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "person_id": "<string>",
      "confidence": 123,
      "timestamp_ms": 123,
      "asset_urls": {},
      "cluster_assignment": {
        "distance_to_person": 123,
        "candidates": [
          {
            "person_id": "<string>",
            "distance": 123,
            "name": "<string>"
          }
        ]
      }
    }
  ],
  "people": [
    {
      "id": "<string>",
      "is_hidden": true,
      "is_favorite": true,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "birth_date": "2023-12-25",
      "asset_count": 123,
      "thumbnail_face_id": "<string>",
      "asset_urls": {},
      "cluster_metrics": {
        "pairwise_p90": 123,
        "pairwise_mean": 123,
        "face_count": 123
      }
    }
  ],
  "width": 0,
  "height": 0,
  "duration": 123,
  "trashed_at": "2023-11-07T05:31:56Z"
}

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 response then falls back to the value embedded in the file when present. latitude and longitude must be set together (both written or both cleared).

Setting or clearing GPS coordinates re-enqueues reverse geocoding so location names refresh against the new effective coordinates.

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

PATCH

api

assets

{asset_id}

Update an asset

curl --request PATCH \
  --url https://api.example.com/api/assets/{asset_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "latitude": 123,
  "longitude": 123,
  "original_datetime": "2023-11-07T05:31:56Z"
}
'

{
  "id": "<string>",
  "mime_type": "<string>",
  "original_file_name": "<string>",
  "local_datetime": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "file_data": {
    "device_asset_id": "<string>",
    "device_id": "<string>",
    "file_created_at": "2023-11-07T05:31:56Z",
    "file_modified_at": "2023-11-07T05:31:56Z",
    "checksum": "<string>",
    "file_size_bytes": 123,
    "checksum_sha1": "<string>"
  },
  "metadata": {
    "asset_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "make": "<string>",
    "model": "<string>",
    "orientation": 123,
    "raw_width": 123,
    "raw_height": 123,
    "modified_datetime": "2023-11-07T05:31:56Z",
    "original_datetime": "2023-11-07T05:31:56Z",
    "digitized_datetime": "2023-11-07T05:31:56Z",
    "lens_model": "<string>",
    "f_number": 123,
    "focal_length": 123,
    "iso": 123,
    "exposure_time": 123,
    "exposure_bias": 123,
    "latitude": 123,
    "longitude": 123,
    "altitude": 123,
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "country_code": "<string>",
    "sublocation": "<string>",
    "place_name": "<string>",
    "timezone": "<string>",
    "display_label": "<string>",
    "description": "<string>",
    "fps": 123,
    "live_photo_cid": "<string>",
    "projection_type": "<string>",
    "auto_stack_id": "<string>",
    "rating": 123
  },
  "metrics": {},
  "asset_urls": {},
  "description": "<string>",
  "thumbhash": "<string>",
  "faces": [
    {
      "id": "<string>",
      "asset_id": "<string>",
      "bounding_box": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "person_id": "<string>",
      "confidence": 123,
      "timestamp_ms": 123,
      "asset_urls": {},
      "cluster_assignment": {
        "distance_to_person": 123,
        "candidates": [
          {
            "person_id": "<string>",
            "distance": 123,
            "name": "<string>"
          }
        ]
      }
    }
  ],
  "people": [
    {
      "id": "<string>",
      "is_hidden": true,
      "is_favorite": true,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "birth_date": "2023-12-25",
      "asset_count": 123,
      "thumbnail_face_id": "<string>",
      "asset_urls": {},
      "cluster_metrics": {
        "pairwise_p90": 123,
        "pairwise_mean": 123,
        "face_count": 123
      }
    }
  ],
  "width": 0,
  "height": 0,
  "duration": 123,
  "trashed_at": "2023-11-07T05:31:56Z"
}

Path Parameters

asset_id

string

required

Asset ID (with asset_ prefix) of the asset to update. Obtain from list_assets, search_assets, or list_album_assets.

Body

application/json

User-editable metadata for a single asset.

Mirrors the field shape of UserAssetMetadataUpdate; the service model owns cross-field validation. See photos-api/docs/references/api-design.md for the router-DTO + service-model pattern.

description

string | null

User-set description for the asset. Pass null to remove a previously-set value (the response then falls back to the description embedded in the file, if any). Omit to leave unchanged. Distinct from the AI-generated description field on the response — this writes to metadata.description.

latitude

number | null

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.

longitude

number | null

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_datetime

string<date-time> | null

When the asset was originally captured. Aware values store the offset from utcoffset() alongside; naive values store NULL offset. Pass null to remove a previously-set value — the response then falls back to the datetime embedded in the file when present, otherwise to the file's upload timestamp. Omit to leave unchanged.

Response

Successful Response

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

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

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

Show child attributes

metadata

MetadataResponse · object

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

Show child attributes

metrics

Metrics · object

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

Show child attributes

asset_urls

Asset Urls · object

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Permanently delete an asset

Update metadata on multiple assets