> ## 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. # Search assets > Searches for assets by content, by typed structured filters on albums, people, date range, and location, or both. Content searches are ranked by relevance; filter-only searches return matches newest-first. Use this tool when the user describes *what's in* the photos they want — subjects, scenes, places, activities, moods, objects — optionally narrowed by album, person, date, or location. Prefer typed filters for anything the request states exactly: `album_id` for album membership, `person_ids` for people, `local_datetime_before`/`local_datetime_after` for date ranges, and `center` + `radius` or `bbox` for location. There is no typed camera or place-name filter — pass those terms in the free-text `query`; the metadata full-text stage can match those terms, while dense retrieval adds visual-semantic matches. For example, 'photos of my kids at the beach last summer' becomes `query='kids at the beach'` + `local_datetime_after=2025-06-01` + `local_datetime_before=2025-09-01`. **Use `list_assets` instead** for a plain structured browse that album, person, date-range, location, or asset-ID filters can answer with no content `query` — it's cheaper and more deterministic than semantic search. **Location filtering is by coordinate,** in two mutually-exclusive modes: a radius (`center` + `radius`) or a bounding box (`bbox`). At least one of `query`, `album_id`, `person_ids`, `local_datetime_before`, or `local_datetime_after` must be provided; a location filter only narrows those results and is not a search criterion on its own. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/search openapi: 3.1.0 info: title: Gumnut API description: >- The Gumnut API manages photo and video libraries: upload and organize assets, search by content, group detected faces into people, and curate albums and stacks. Headless clients authenticate by sending either a Gumnut API key (`apikey_...`) or an OAuth access token as a Bearer token in the `Authorization` header. The Gumnut web and mobile apps sign in with a first-party session (Clerk session JWT) instead, which is also the only credential that can manage API keys. contact: name: Gumnut url: https://www.gumnut.ai/contact version: 1.0.0 servers: - url: https://api.gumnut.ai description: Production security: - apiKeyAuth: [] - oauthJwtAuth: [] tags: - name: assets description: >- Photos and videos in a library: upload, list and filter, update metadata, trash and restore. - name: search description: >- Content-based search over a library's assets, with the same filters as asset listing. - name: albums description: User-curated collections of assets. - name: album-assets description: Link records connecting albums to their member assets. - name: stacks description: >- Groups of related shots of the same moment, presented as a single unit with a cover asset. - name: people description: Named people, each built from clustered faces. - name: faces description: Detected faces and their assignment to people. - name: libraries description: Top-level containers that own assets, albums, people, and everything else. - name: events description: Change-event feed for keeping client state in sync. - name: tasks description: Status of background processing tasks. - name: users description: The authenticated user's profile. - name: api-keys description: >- Create and manage Gumnut API keys. Requires a first-party Gumnut app session — API keys and OAuth tokens cannot manage credentials. - name: oauth description: OAuth flow endpoints for obtaining and refreshing access tokens. - name: server description: Service health. paths: /api/search: get: tags: - search summary: Search assets description: >- Searches for assets by content, by typed structured filters on albums, people, date range, and location, or both. Content searches are ranked by relevance; filter-only searches return matches newest-first. Use this tool when the user describes *what's in* the photos they want — subjects, scenes, places, activities, moods, objects — optionally narrowed by album, person, date, or location. Prefer typed filters for anything the request states exactly: `album_id` for album membership, `person_ids` for people, `local_datetime_before`/`local_datetime_after` for date ranges, and `center` + `radius` or `bbox` for location. There is no typed camera or place-name filter — pass those terms in the free-text `query`; the metadata full-text stage can match those terms, while dense retrieval adds visual-semantic matches. For example, 'photos of my kids at the beach last summer' becomes `query='kids at the beach'` + `local_datetime_after=2025-06-01` + `local_datetime_before=2025-09-01`. **Use `list_assets` instead** for a plain structured browse that album, person, date-range, location, or asset-ID filters can answer with no content `query` — it's cheaper and more deterministic than semantic search. **Location filtering is by coordinate,** in two mutually-exclusive modes: a radius (`center` + `radius`) or a bounding box (`bbox`). At least one of `query`, `album_id`, `person_ids`, `local_datetime_before`, or `local_datetime_after` must be provided; a location filter only narrows those results and is not a search criterion on its own. operationId: search_assets parameters: - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Library Id description: >- Library to search. Optional if the user has a single live (non-trashed) library; required when they have multiple. description: >- Library to search. Optional if the user has a single live (non-trashed) library; required when they have multiple. - name: query in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- Natural-language search text. It runs independently through dense visual retrieval and authoritative-metadata full-text retrieval, then the ranked lists are fused. Concrete visual concepts work well in the dense stage, while exact metadata terms can match through full-text search. Resolve album and people names to IDs and pass them as `album_id` and `person_ids`; convert date phrases like 'in 2023' into ISO 8601 bounds on `local_datetime_after`/`local_datetime_before` (here, `2023-01-01` and `2024-01-01`). None of those belong in `query`. title: Query description: >- Natural-language search text. It runs independently through dense visual retrieval and authoritative-metadata full-text retrieval, then the ranked lists are fused. Concrete visual concepts work well in the dense stage, while exact metadata terms can match through full-text search. Resolve album and people names to IDs and pass them as `album_id` and `person_ids`; convert date phrases like 'in 2023' into ISO 8601 bounds on `local_datetime_after`/`local_datetime_before` (here, `2023-01-01` and `2024-01-01`). None of those belong in `query`. - name: person_ids in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Filter to assets containing ALL of these person IDs (intersection, not union). Accepts multiple `person_ids=` query params or a single comma-delimited value (e.g., `person_123,person_abc`). Person IDs are carried by the entries of an asset's `people` field (returned with `include=people`). title: Person Ids description: >- Filter to assets containing ALL of these person IDs (intersection, not union). Accepts multiple `person_ids=` query params or a single comma-delimited value (e.g., `person_123,person_abc`). Person IDs are carried by the entries of an asset's `people` field (returned with `include=people`). - name: album_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Album Id description: >- Return only assets in this album — the album's `album_` ID, not its name. description: >- Return only assets in this album — the album's `album_` ID, not its name. - 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' 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`. 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`. - name: radius in: query required: false schema: anyOf: - type: number - type: 'null' title: Radius description: >- Radius of the `center` location filter, in meters (greater than 0, at most 50,000). description: >- Radius of the `center` location filter, in meters (greater than 0, at most 50,000). - name: bbox in: query required: false schema: anyOf: - type: string - type: 'null' 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. 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. - name: page in: query required: false schema: type: integer minimum: 1 title: Page description: >- 1-indexed page number; increment it to fetch subsequent pages. `search_assets` pages by number rather than by cursor. A search with a content criterion ranks a fixed top-200 candidate population by relevance, so pages beyond that population are empty. A structured-filter-only search (album, people, date range — no content criterion) returns the full matching set newest-first, paginated without that cap. default: 1 description: >- 1-indexed page number; increment it to fetch subsequent pages. `search_assets` pages by number rather than by cursor. A search with a content criterion ranks a fixed top-200 candidate population by relevance, so pages beyond that population are empty. A structured-filter-only search (album, people, date range — no content criterion) returns the full matching set newest-first, paginated without that cap. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 title: Limit description: Maximum number of results per page (1–200). Defaults to 20. default: 20 description: Maximum number of results 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` (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, `description`, `thumbhash`, `asset_urls`, `kind`, `current_version_id`) 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` (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, `description`, `thumbhash`, `asset_urls`, `kind`, `current_version_id`) and each data field above is null/absent until you request it. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchAssetsResponse' '401': description: Missing, invalid, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Rate limit exceeded. Retry after the interval in the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SearchAssetsResponse: properties: data: items: $ref: '#/components/schemas/SearchResultItem' type: array title: Data description: >- Text-query matches use the configured reranker over the first 50 Reciprocal Rank Fusion candidates, with fail-open RRF ordering. Image-only matches use RRF across available stages. Structured-filter-only searches retain newest-first capture-date ordering. type: object required: - data title: SearchAssetsResponse ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SearchResultItem: properties: asset: $ref: '#/components/schemas/AssetResponse' description: The matching asset. distance: anyOf: - type: number - type: 'null' title: Distance description: >- Best available dense-stage cosine distance (lower is more similar). This is attribution only: text results use reranker order when reranking succeeds and RRF order on fallback; image-only results use RRF. Results are never ordered by this distance. Null for sparse-only and structured-filter-only matches. type: object required: - asset - distance title: SearchResultItem ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError 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 current rendering (e.g., 'image/jpeg', 'video/mp4'). original_file_name: type: string title: Original File Name description: Filename the asset was uploaded under. 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 (