> ## 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. # List assets in a library > Returns a paginated list of assets ordered by local capture time (or trash time for trashed assets), newest first by default, optionally filtered by album, person, date range, geographic area, or asset ID. Use this tool for structured browsing and filtering — when the request can be expressed as exact filters on album membership, people, date range, geographic coordinates, or specific asset IDs. **Location filtering is by coordinate:** pass a radius (`center` + `radius`) or a bounding box (`bbox`) to restrict results to a geographic area. The two modes are mutually exclusive. To count or cluster geotagged assets across a map viewport (how many photos fall in each area) rather than list them, use `get_geo_clusters`. Album and person filters compose using AND; do not supply both `person_id` and `person_ids`. **Use `search_assets` instead** when the request involves natural-language image content ('photos of sunsets', 'pictures with my dog'), a place *name* ('photos from Japan'), or any concept requiring semantic understanding of what's in the image. `list_assets` filters by coordinate but not by image content, place name, 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: while `has_more` is true, keep fetching with `starting_after_id`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/assets openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/assets: get: tags: - assets summary: List assets in a library description: >- Returns a paginated list of assets ordered by local capture time (or trash time for trashed assets), newest first by default, optionally filtered by album, person, date range, geographic area, or asset ID. Use this tool for structured browsing and filtering — when the request can be expressed as exact filters on album membership, people, date range, geographic coordinates, or specific asset IDs. **Location filtering is by coordinate:** pass a radius (`center` + `radius`) or a bounding box (`bbox`) to restrict results to a geographic area. The two modes are mutually exclusive. To count or cluster geotagged assets across a map viewport (how many photos fall in each area) rather than list them, use `get_geo_clusters`. Album and person filters compose using AND; do not supply both `person_id` and `person_ids`. **Use `search_assets` instead** when the request involves natural-language image content ('photos of sunsets', 'pictures with my dog'), a place *name* ('photos from Japan'), or any concept requiring semantic understanding of what's in the image. `list_assets` filters by coordinate but not by image content, place name, 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: while `has_more` is true, keep fetching with `starting_after_id`. operationId: list_assets parameters: - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Library to list assets from. Optional if the user has a single library; required when they have multiple. title: Library Id description: >- Library to list assets from. Optional if the user has a single library; required when they have multiple. - name: album_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only assets in this album — the album's `album_` ID, not its name. To browse one album's full asset metadata, prefer this filter over `list_album_assets`, which returns link records. title: Album Id description: >- Return only assets in this album — the album's `album_` ID, not its name. To browse one album's full asset metadata, prefer this filter over `list_album_assets`, which returns link records. - name: person_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Deprecated compatibility alias for a single `person_ids` value. deprecated: true title: Person Id description: Deprecated compatibility alias for a single `person_ids` value. deprecated: true - name: person_ids in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Return only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated `person_ids=` query params or comma-delimited values. Person IDs are carried by the entries of an asset's `people` field (returned with `include=people`). title: Person Ids description: >- Return only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated `person_ids=` query params or comma-delimited values. Person IDs are carried by the entries of an asset's `people` field (returned with `include=people`). - name: stack_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only assets belonging to this stack (the `asset_stack_` ID carried by the `stack_id` field on every asset). title: Stack Id description: >- Return only assets belonging to this stack (the `asset_stack_` ID carried by the `stack_id` field on every asset). - name: ids in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Look up specific assets by ID (max 200; each ID has the `asset_` prefix). Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=asset_1,asset_2`). Combines with other filters (album_id, person_ids, stack_id, datetime range) using AND logic — the result is the intersection. title: Ids description: >- Look up specific assets by ID (max 200; each ID has the `asset_` prefix). Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=asset_1,asset_2`). Combines with other filters (album_id, person_ids, stack_id, datetime range) using AND logic — the result is the intersection. - name: local_datetime_after in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Local Datetime After description: >- Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. `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`. description: >- Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. `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`. - name: local_datetime_before in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Local Datetime Before description: >- Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as `local_datetime_after`. description: >- Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as `local_datetime_after`. - name: center in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Center point of a radius location filter: two comma-separated decimal-degree numbers `longitude,latitude`, e.g. `-77.05,38.95`. Supply with `radius`. Mutually exclusive with `bbox`. title: Center description: >- Center point of a radius location filter: two comma-separated decimal-degree numbers `longitude,latitude`, e.g. `-77.05,38.95`. Supply with `radius`. Mutually exclusive with `bbox`. - name: radius in: query required: false schema: anyOf: - type: number - type: 'null' description: >- Radius of the `center` location filter, in meters (greater than 0, at most 50000). title: Radius description: >- Radius of the `center` location filter, in meters (greater than 0, at most 50000). - name: bbox in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers `min_longitude,min_latitude,max_longitude,max_latitude` (west,south,east,north), e.g. `-77.1,38.9,-77.0,39.0`. A box whose `min_longitude` exceeds `max_longitude` crosses the antimeridian: it selects the band running east from `min_longitude` over ±180° to `max_longitude`, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range `-180,...,180,...`, which the wrapped form cannot express. Mutually exclusive with `center`/`radius`. title: Bbox description: >- Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers `min_longitude,min_latitude,max_longitude,max_latitude` (west,south,east,north), e.g. `-77.1,38.9,-77.0,39.0`. A box whose `min_longitude` exceeds `max_longitude` crosses the antimeridian: it selects the band running east from `min_longitude` over ±180° to `max_longitude`, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range `-180,...,180,...`, which the wrapped form cannot express. Mutually exclusive with `center`/`radius`. - name: starting_after_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Cursor for pagination. Pass the `id` of the last asset in the previous response's `data` to fetch the next page. Repeat the same filters, `state`, and `order` on every page. Omit for the first page. `list_assets` cursors because it walks a stable capture-time ordering; the sibling `search_assets` ranks by relevance and so pages by number instead. title: Starting After Id description: >- Cursor for pagination. Pass the `id` of the last asset in the previous response's `data` to fetch the next page. Repeat the same filters, `state`, and `order` on every page. Omit for the first page. `list_assets` cursors because it walks a stable capture-time ordering; the sibling `search_assets` ranks by relevance and so pages by number instead. - name: state in: query required: false schema: enum: - live - trashed - all type: string description: >- Which set of assets to read from: `live` (default — only assets that are not trashed), `trashed` (only trashed assets, ordered by trash time), or `all` (both live and trashed, ordered by capture time like `live`). Ordering defaults to newest or most recently trashed first. default: live title: State description: >- Which set of assets to read from: `live` (default — only assets that are not trashed), `trashed` (only trashed assets, ordered by trash time), or `all` (both live and trashed, ordered by capture time like `live`). Ordering defaults to newest or most recently trashed first. - name: order in: query required: false schema: enum: - asc - desc type: string description: >- Sort direction for the selected state's timestamp: capture time for `live`/`all`, or trash time for `trashed`. The asset ID tie-breaker uses the same direction. default: desc title: Order description: >- Sort direction for the selected state's timestamp: capture time for `live`/`all`, or trash time for `trashed`. The asset ID tie-breaker uses the same direction. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: >- Maximum number of assets to return per page (1–200). Defaults to 20. default: 20 title: Limit description: Maximum number of assets to return per page (1–200). Defaults to 20. - name: include in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Opt-in expansion fields. Supported values: `metadata` (camera/EXIF/GPS and location names), `faces`, `people`, `metrics` (ML quality scores), `file_data` (a group token populating the nested `file_data` object with the file/provenance scalars `device_asset_id`, `device_id`, `file_created_at`, `file_modified_at`, `checksum`, `checksum_sha1`, `file_size_bytes`), and `variants` (the non-thumbnail `asset_urls` size variants; without it `asset_urls` carries only its lean rung — `thumbnail`, or `thumbnail_image` for a video with an extracted still, or `original` for a still-less video — so callers that render non-thumbnail variants must pass it). Accepts multiple `include=` query params or a single comma-delimited value (e.g. `include=faces,people`). Unknown values return 422. When omitted, only the lean core is returned (`id`, `mime_type`, `local_datetime`, dimensions, `description`, `thumbhash`, `asset_urls`) and each data field above is null/absent until you request it. title: Include description: >- Opt-in expansion fields. Supported values: `metadata` (camera/EXIF/GPS and location names), `faces`, `people`, `metrics` (ML quality scores), `file_data` (a group token populating the nested `file_data` object with the file/provenance scalars `device_asset_id`, `device_id`, `file_created_at`, `file_modified_at`, `checksum`, `checksum_sha1`, `file_size_bytes`), and `variants` (the non-thumbnail `asset_urls` size variants; without it `asset_urls` carries only its lean rung — `thumbnail`, or `thumbnail_image` for a video with an extracted still, or `original` for a still-less video — so callers that render non-thumbnail variants must pass it). Accepts multiple `include=` query params or a single comma-delimited value (e.g. `include=faces,people`). Unknown values return 422. When omitted, only the lean core is returned (`id`, `mime_type`, `local_datetime`, dimensions, `description`, `thumbhash`, `asset_urls`) and each data field above is null/absent until you request it. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedAssetsResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PaginatedAssetsResponse: properties: data: items: $ref: '#/components/schemas/AssetResponse' type: array title: Data description: List of assets has_more: type: boolean title: Has More description: >- True if there are more assets after this page. Pass the last asset's `id` as `starting_after_id` and repeat the same filters, `state`, and `order` to fetch the next page. type: object required: - data - has_more title: PaginatedAssetsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AssetResponse: properties: id: type: string title: Id description: Unique asset identifier with 'asset_' prefix mime_type: type: string title: Mime Type description: MIME type of the file (e.g., 'image/jpeg', 'video/mp4') original_file_name: type: string title: Original File Name description: Original filename when the asset was uploaded local_datetime: type: string format: date-time title: Local Datetime description: When the photo/video was taken, in the device's local timezone file_data: anyOf: - $ref: '#/components/schemas/FileDataResponse' - type: 'null' description: >- 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). created_at: type: string format: date-time title: Created At description: When this asset record was created in the database updated_at: type: string format: date-time title: Updated At description: When this asset record was last updated metadata: anyOf: - $ref: '#/components/schemas/MetadataResponse' - type: 'null' description: >- Asset metadata — camera/EXIF fields, GPS, and location names. `null` when not requested via `include=metadata`. metrics: anyOf: - additionalProperties: anyOf: - type: number - type: 'null' type: object - type: 'null' title: Metrics description: >- ML-generated quality scores and other metrics. `null` when not requested via `include=metrics`. asset_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Asset Urls description: >- 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 (