--- title: "Update an asset" method: PATCH path: "/api/assets/{asset_id}" tags: ["assets"] --- # Update an asset `PATCH /api/assets/{asset_id}` 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`. ## Path parameters - `asset_id` string, required — Asset ID (with `asset_` prefix) of the asset to update. ## Request body - UpdateAssetRequest — 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, nullable — 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, 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. - `longitude` number, 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_datetime` string, date-time, nullable — 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 `200` Successful Response - AssetResponse — Represents a photo or video asset with metadata and access URLs. Top-level fields describe the asset's current rendering (the version identified by `current_version_id`) unless they explicitly name the original upload, like `original_file_name` and the `file_data` group. - `id` string, required — Unique asset identifier with 'asset_' prefix - `mime_type` string, required — MIME type of the current rendering (e.g., 'image/jpeg', 'video/mp4'). - `original_file_name` string, required — Filename the asset was uploaded under. - `local_datetime` string, date-time, required — When the photo/video was taken, in the device's local timezone - `file_data` FileDataResponse — File/provenance scalars describing the uploaded *file* (not its content). Returned only when requested via ``include=file_data``; the whole object is ``null`` otherwise. When present, every field carries its real value — ``checksum_sha1`` is the lone exception (``null`` for legacy rows that never had a SHA-1). This nested object is the home for the file/provenance group. - `device_asset_id` string, required — Original asset identifier from the device that uploaded this asset. - `device_id` string, required — Identifier of the device that uploaded this asset. - `file_created_at` string, date-time, required — When the file was created on the uploading device. - `file_modified_at` string, date-time, required — When the file was last modified on the uploading device. - `checksum` string, required — Base64-encoded SHA-256 hash of the asset contents for duplicate detection and integrity. - `checksum_sha1` string, nullable — Base64-encoded SHA-1 hash of the asset contents. `null` for older assets that have no SHA-1. - `file_size_bytes` integer, required — Size of the uploaded file in bytes. Each rendering's own size is on its row in the asset's version listing. - `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 - `metadata` MetadataResponse — Metadata for an asset — camera/EXIF fields, GPS, and location names. - `asset_id` string, required — ID of the asset this metadata belongs to - `created_at` string, date-time, required — When this metadata record was created - `updated_at` string, date-time, required — When this metadata record was last updated - `make` string, nullable — Camera manufacturer (e.g., 'Canon', 'Nikon') - `model` string, nullable — Camera model (e.g., 'EOS 5D Mark IV') - `orientation` integer, nullable — Image orientation value (1-8) indicating rotation/flip: 1=normal, 2=mirror horizontal, 3=rotate 180°, 4=mirror vertical, 5=mirror horizontal+rotate 90° CW, 6=rotate 90° CW, 7=mirror horizontal+rotate 90° CCW, 8=rotate 90° CCW - `raw_width` integer, nullable — Pre-rotation raw width; null when not available - `raw_height` integer, nullable — Pre-rotation raw height; null when not available - `modified_datetime` string, date-time, nullable — When the file was last modified, with timezone offset if available - `original_datetime` string, date-time, nullable — When the photo was originally taken, with timezone offset if available - `digitized_datetime` string, date-time, nullable — When the photo was digitized, with timezone offset if available - `lens_model` string, nullable — Lens model used (e.g., 'EF 24-70mm f/2.8L II USM') - `f_number` number, nullable — Aperture f-stop value (e.g., 2.8, 5.6) - `focal_length` number, nullable — Focal length in millimeters - `iso` integer, nullable — ISO sensitivity value (e.g., 100, 800, 3200) - `exposure_time` number, nullable — Shutter speed in seconds (e.g., 0.001 for 1/1000s) - `exposure_bias` number, nullable — Exposure compensation in EV (e.g., -1.0, +0.5) - `latitude` number, nullable — GPS latitude in decimal degrees - `longitude` number, nullable — GPS longitude in decimal degrees - `altitude` number, nullable — GPS altitude in meters - `city` string, nullable — City name - `state` string, nullable — State/province name - `country` string, nullable — Country name - `country_code` string, nullable — ISO 3166-1 alpha-2 country code (e.g., 'US', 'JP') - `sublocation` string, nullable — Neighborhood or district - `place_name` string, nullable — Landmark or point-of-interest name - `timezone` string, nullable — IANA timezone identifier (e.g., 'America/Los_Angeles') - `display_label` string, nullable — Human-readable location label. Picks the most specific available identifier (place_name > sublocation > city > country) and appends broader context (city, then state-or-country). Example: 'Golden Gate Bridge, San Francisco, California'. Null when no location fields are populated. - `description` string, nullable — Image description or caption - `fps` number, nullable — Frame rate for video files - `live_photo_cid` string, nullable — Live photo content identifier - `projection_type` string, nullable — Projection type (e.g., for 360° photos) - `auto_stack_id` string, nullable — Identifier for automatic photo stacking - `rating` integer, nullable — User or camera rating (typically 1-5 stars) - `metrics` object, nullable — ML-generated quality scores and other metrics. `null` when not requested via `include=metrics`. - `asset_urls` object, 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 (