Skip to main content
GET
List assets in a library

Authorizations

Authorization
string
header
required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Query Parameters

library_id
string | null

Library to list assets from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

album_id
string | null

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.

album_filter
enum<string>
default:all

Filter by album membership in general, rather than by membership of one specific album. This filter is independent of album_id, but combining not_in_album with album_id is contradictory and returns 422. Defaults to all.

Available options:
all,
in_album,
not_in_album
person_ids
string[] | null

Filter to 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).

stack_id
string | null

Return only assets belonging to this stack (the asset_stack_ ID carried by the stack_id field on every asset).

media_type
enum<string> | null

Filter to one media class (image or video). Omit to include both images and videos. Which media class an asset belongs to.

Every image format is image and every video format is video. An asset's class is fixed by the file originally uploaded, so an edited photo is still image.

Available options:
image,
video
ratings
integer[] | null

Return assets whose effective rating is one of these exact values. Values must be integers from 0 through 5; 5 is a favorite. 0 matches every unrated form: an explicit zero, a null or legacy out-of-range effective rating, or an asset with no metadata. Accepts repeated ratings= parameters or one comma-delimited value. Omit the parameter for no rating filter.

Required range: 0 <= x <= 5
ids
string[] | null

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, media_type, ratings, datetime range) using AND logic — the result is the intersection.

local_datetime_after
string<date-time> | null

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.

local_datetime_before
string<date-time> | null

Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.

center
string | null

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.

radius
number | null

Radius of the center location filter, in meters (greater than 0, at most 50,000). Supply with center. Mutually exclusive with bbox.

bbox
string | null

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.

starting_after_id
string | null

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.

state
enum<string>
default:live

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.

Available options:
live,
trashed,
all
order
enum<string>
default:desc

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.

Available options:
asc,
desc
limit
integer
default:20

Maximum number of assets to return per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200
include
string[] | null

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 (every asset_urls rung beyond the lean one. Without it asset_urls carries only its lean rung — thumbnail for an image, or thumbnail_image for a video — so callers that render non-thumbnail variants or download the current rendering 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, file_size_bytes, description, thumbhash, asset_urls, kind, current_version_id) and each data field above is null/absent until you request it.

Response

Successful Response

data
AssetResponse · object[]
required

List of assets

has_more
boolean
required

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.