Skip to main content
POST
/
api
/
search
Search assets
curl --request POST \
  --url https://api.example.com/api/search \
  --header 'Content-Type: multipart/form-data' \
  --form 'library_id=<string>' \
  --form 'query=<string>' \
  --form 'image=<string>' \
  --form 'person_ids=<string>' \
  --form captured_before=2023-11-07T05:31:56Z \
  --form captured_after=2023-11-07T05:31:56Z \
  --form page=1 \
  --form limit=20 \
  --form threshold=0.8 \
  --form image.0='@example-file'
{
  "data": [
    {
      "asset": {
        "id": "<string>",
        "mime_type": "<string>",
        "original_file_name": "<string>",
        "local_datetime": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "file_data": {
          "device_asset_id": "<string>",
          "device_id": "<string>",
          "file_created_at": "2023-11-07T05:31:56Z",
          "file_modified_at": "2023-11-07T05:31:56Z",
          "checksum": "<string>",
          "file_size_bytes": 123,
          "checksum_sha1": "<string>"
        },
        "metadata": {
          "asset_id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "make": "<string>",
          "model": "<string>",
          "orientation": 123,
          "raw_width": 123,
          "raw_height": 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>",
        "thumbhash": "<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>",
            "confidence": 123,
            "timestamp_ms": 123,
            "asset_urls": {},
            "cluster_assignment": {
              "distance_to_person": 123,
              "candidates": [
                {
                  "person_id": "<string>",
                  "distance": 123,
                  "name": "<string>"
                }
              ]
            }
          }
        ],
        "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": {},
            "cluster_metrics": {
              "pairwise_p90": 123,
              "pairwise_mean": 123,
              "face_count": 123
            }
          }
        ],
        "width": 0,
        "height": 0,
        "duration": 123,
        "trashed_at": "2023-11-07T05:31:56Z"
      },
      "distance": 123
    }
  ]
}

Query Parameters

​
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 (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.

Body

multipart/form-data
​
library_id
string | null

Library to search assets from (optional)

​
query
string | null

The text query to search for. If you want to search for a specific person or set of people, use the person_ids parameter instead.If you want to search for a photos taken during a specific date range, use the captured_before and captured_after parameters instead.

​
image
file | null

Image file to search for similar assets. Can be combined with text query.

​
person_ids
string[] | null

Filter to assets containing ALL of these person IDs (intersection, not union). Accepts multiple person_ids= form fields or a single comma-delimited value (e.g., person_123,person_abc). Get person IDs from list_people.

​
captured_before
string<date-time> | null

Filter to only include assets captured before this date (ISO format).

​
captured_after
string<date-time> | null

Filter to only include assets captured after this date (ISO format).

​
page
integer
default:1

Page number

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

Number of results per page (1-200)

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

Similarity threshold (lower 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.