Skip to main content
GET
/
api
/
search
Search assets by natural-language image content, people, or date range
curl --request GET \
  --url https://api.example.com/api/search
{
  "data": [
    {
      "asset": {
        "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"
      },
      "distance": 123
    }
  ]
}

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_id
string | null

Library to search. Optional if the user has a single library; required when they have multiple. Use list_libraries to enumerate available libraries.

​
query
string | null

Natural-language description of the image content to search for. Matched against CLIP image embeddings, so it works best with concrete visual concepts: subjects, scenes, objects, settings ('beach sunset', 'birthday cake', 'mountain hike').

Prefer structured params when available: use person_ids for people (not names in query) and captured_before/captured_after for dates (not phrases like 'in 2023' in query).

​
person_ids
string[] | null

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). Get person IDs from list_people. Plural on this tool; the sibling list_assets uses person_id (singular).

​
captured_before
string<date-time> | null

Only include assets captured strictly before this instant (ISO 8601; exclusive). Equivalent in purpose to local_datetime_before on list_assets (naming inconsistency is tracked as a follow-up).

​
captured_after
string<date-time> | null

Only include assets captured strictly after this instant (ISO 8601; exclusive). Equivalent in purpose to local_datetime_after on list_assets (naming inconsistency is tracked as a follow-up).

​
page
integer
default:1

1-indexed page number. search_assets uses page-number pagination; the sibling list_assets uses cursor pagination via starting_after_id. Increment page to fetch subsequent pages.

Required range: x >= 1
​
limit
integer
default:20

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

Required range: 1 <= x <= 200
​
threshold
number
default:0.8

Maximum semantic distance for a result to be included (0.0 = identical, 1.0 = unrelated). Lower values return fewer, more confident matches; higher values return more results with looser matching. Default 0.8 is moderate — try 0.6 for high-precision queries, 0.9 for exploratory searches. Note: this is inverted from the usual 'similarity score' convention where higher means more similar.

Required range: 0 <= x <= 1

Response

Successful Response

​
data
SearchResultItem · object[]
required

Matching assets ordered by semantic distance (closest first) when query is set.