oauth
assets
- GETList assets in a library, optionally filtered by album, person, date range, or asset ID
- POSTUpload a new asset
- DELPermanently delete the specified assets and their underlying files
- GETGet asset counts
- POSTCheck asset existence
- POSTMove assets to trash
- POSTRestore assets from trash
- POSTPermanently delete every trashed asset in the library
- GETGet full metadata for a single asset by ID
- DELPermanently delete an asset and its underlying file
album-assets
albums
- GETList albums in a library, optionally filtered by asset membership or ID
- POSTCreate a new, empty album in a library
- GETGet metadata for a single album by ID
- DELDelete an album (the assets inside it are kept)
- PATCHRename an album or change its description
- POSTAdd existing assets to an album
- DELRemove assets from an album (assets themselves are kept)
libraries
faces
people
- GETList people in a library, optionally filtered by asset, album, name, or ID
- POSTCreate a new person record (a named identity for grouping faces)
- GETGet metadata for a single person by ID
- DELDelete a person record; its faces become unassigned and will be re-clustered
- PATCHUpdate a person's name, birth date, visibility, or thumbnail
- POSTMerge people
server
curl --request GET \
--url https://api.example.com/api/assets{
"data": [
{
"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>",
"exif": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 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>",
"description": "<string>",
"fps": 123,
"live_photo_cid": "<string>",
"projection_type": "<string>",
"profile_description": "<string>",
"auto_stack_id": "<string>",
"rating": 123
},
"metadata": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 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": {}
}
],
"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": {}
}
],
"width": 0,
"height": 0,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}
],
"has_more": true
}List assets in a library, optionally filtered by album, person, date range, or asset ID
Returns a paginated list of assets ordered by local capture time (newest first). Use this tool for structured browsing and filtering — when the request can be expressed as exact filters on album membership, people, date range, or specific asset IDs.
Use search_assets instead when the request involves natural-language image content (‘photos of sunsets’, ‘pictures with my dog’), location or place (‘photos from Japan’), or any concept requiring semantic understanding of what’s in the image. list_assets does not filter by image content, location, or caption text.
To present a curated set of specific assets to the user (e.g., a hand-picked subset of search_assets results), call this tool with ids=[...] rather than building a custom gallery — the asset IDs you already have are enough to re-render them through the interactive widget.
Pagination is cursor-based: when has_more is true, pass the id of the last asset in data as starting_after_id to fetch the next page.
curl --request GET \
--url https://api.example.com/api/assets{
"data": [
{
"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>",
"exif": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 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>",
"description": "<string>",
"fps": 123,
"live_photo_cid": "<string>",
"projection_type": "<string>",
"profile_description": "<string>",
"auto_stack_id": "<string>",
"rating": 123
},
"metadata": {
"asset_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"make": "<string>",
"model": "<string>",
"orientation": 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": {}
}
],
"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": {}
}
],
"width": 0,
"height": 0,
"file_size_bytes": 0,
"trashed_at": "2023-11-07T05:31:56Z"
}
],
"has_more": true
}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.
Query Parameters
Library to list assets from. Optional if the user has a single library; required when they have multiple. Use list_libraries to enumerate available libraries.
Return only assets that are in the album with this ID. Equivalent to calling list_album_assets with album_id and then fetching each asset — prefer this param when you need the full asset metadata in one call.
Return only assets containing a face belonging to this person. Singular on this tool; the sibling search_assets uses person_ids (plural, ALL-of).
Look up specific assets by ID (max 100; each ID has the asset_ prefix). Use this for bulk fetch when you already have asset IDs. Combines with other filters (album_id, person_id, datetime range) using AND logic — the result is the intersection.
Only include assets captured strictly after this instant (ISO 8601; exclusive). local_datetime is the photo's wall-clock time in the device's own timezone. Naive values compare directly against local_datetime. Timezone-aware values: assets with a known offset are compared in UTC (local_datetime - offset); assets without an offset fall back to wall-clock comparison against local_datetime. Equivalent in purpose to captured_after on search_assets (naming inconsistency is tracked as a follow-up).
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same awareness/offset semantics as local_datetime_after. Equivalent in purpose to captured_before on search_assets (naming inconsistency is tracked as a follow-up).
Cursor for pagination. Pass the id of the last asset in the previous response's data to fetch the next page. Omit for the first page. list_assets uses cursor pagination; the sibling search_assets uses 1-indexed page numbers (naming inconsistency is tracked as a follow-up).
Which set of assets to read from: live (default — only assets that are not trashed), trashed (only trashed assets, ordered by most recently trashed), or all (both live and trashed, ordered by capture time like live).
live, trashed, all Maximum number of assets to return per page (1–200). Defaults to 20.
1 <= x <= 200