--- 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 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`. ## 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. - `description` string, 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`. - `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. 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 `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 (