oauth
assets
albums
libraries
people
server
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>",
"device_asset_id": "<string>",
"device_id": "<string>",
"mime_type": "<string>",
"original_file_name": "<string>",
"file_created_at": "2023-11-07T05:31:56Z",
"file_modified_at": "2023-11-07T05:31:56Z",
"local_datetime": "2023-11-07T05:31:56Z",
"checksum": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"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>",
"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>",
"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,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}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. Setting the datetime moves the asset in the timeline (list_assets ordering).
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>",
"device_asset_id": "<string>",
"device_id": "<string>",
"mime_type": "<string>",
"original_file_name": "<string>",
"file_created_at": "2023-11-07T05:31:56Z",
"file_modified_at": "2023-11-07T05:31:56Z",
"local_datetime": "2023-11-07T05:31:56Z",
"checksum": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"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>",
"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>",
"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,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}Documentation Index
Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
Use this file to discover all available pages before exploring further.
Path Parameters
Asset ID (with asset_ prefix) of the asset to update. Obtain from list_assets, search_assets, or list_album_assets.
Body
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.
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.
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.
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.
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.
Unique asset identifier with 'asset_' prefix
Original asset identifier from the device that uploaded this asset
Identifier of the device that uploaded this asset
MIME type of the file (e.g., 'image/jpeg', 'video/mp4')
Original filename when the asset was uploaded
When the file was created on the uploading device
When the file was last modified on the uploading device
When the photo/video was taken, in the device's local timezone
Base64-encoded SHA-256 hash of the asset contents for duplicate detection and integrity
When this asset record was created in the database
When this asset record was last updated
Base64-encoded SHA-1 hash for Immich client compatibility. May be null for older assets.
Asset metadata — camera/EXIF fields, GPS, and location names.
Show child attributes
Show child attributes
ML-generated quality scores and other metrics
Show child attributes
Show child attributes
Named asset variants: 'original', 'thumbnail', 'preview', 'fullsize' for images; 'original' only for videos
Show child attributes
Show child attributes
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).
All faces detected in this asset
Show child attributes
Show child attributes
All unique people identified in this asset (deduplicated from faces)
Show child attributes
Show child attributes
Width of the asset in pixels
Height of the asset in pixels
File size of the asset in bytes
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.