Search assets

curl --request POST \
  --url https://api.gumnut.ai/api/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'library_id=<string>' \
  --form 'query=<string>' \
  --form 'image=<string>' \
  --form 'person_ids=<string>' \
  --form 'album_id=<string>' \
  --form ratings=2 \
  --form local_datetime_after=2023-11-07T05:31:56Z \
  --form local_datetime_before=2023-11-07T05:31:56Z \
  --form 'center=<string>' \
  --form radius=123 \
  --form 'bbox=<string>' \
  --form page=1 \
  --form limit=20 \
  --form image.0='@example-file'

import requests

url = "https://api.gumnut.ai/api/search"

files = { "image.0": ("example-file", open("example-file", "rb")) }
payload = {
    "library_id": "<string>",
    "query": "<string>",
    "image": "<string>",
    "person_ids": "<string>",
    "album_id": "<string>",
    "ratings": "2",
    "local_datetime_after": "2023-11-07T05:31:56Z",
    "local_datetime_before": "2023-11-07T05:31:56Z",
    "center": "<string>",
    "radius": "123",
    "bbox": "<string>",
    "page": "1",
    "limit": "20"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('library_id', '<string>');
form.append('query', '<string>');
form.append('image', '<string>');
form.append('person_ids', '<string>');
form.append('album_id', '<string>');
form.append('ratings', '2');
form.append('local_datetime_after', '2023-11-07T05:31:56Z');
form.append('local_datetime_before', '2023-11-07T05:31:56Z');
form.append('center', '<string>');
form.append('radius', '123');
form.append('bbox', '<string>');
form.append('page', '1');
form.append('limit', '20');
form.append('image.0', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.gumnut.ai/api/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumnut.ai/api/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumnut.ai/api/search"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gumnut.ai/api/search")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gumnut.ai/api/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "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",
        "kind": "<string>",
        "current_version_id": "<string>",
        "file_size_bytes": 123,
        "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": {},
            "source": "automatic",
            "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",
        "stack_id": "<string>"
      },
      "distance": 123
    }
  ],
  "has_more": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Search assets

Searches for assets by content, by typed structured filters, or both. Content searches are ranked by relevance; filter-only searches return matches newest-first. An uploaded image adds visual-similarity search; text and uploaded-image signals stay independent when both are provided.

At least one search criterion, including ratings or media_type, must be provided. Location filtering is by coordinate in two mutually-exclusive modes: a radius (center + radius) or a bounding box (bbox); it narrows candidates and is not a search criterion on its own.

POST

api

Search assets

curl --request POST \
  --url https://api.gumnut.ai/api/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'library_id=<string>' \
  --form 'query=<string>' \
  --form 'image=<string>' \
  --form 'person_ids=<string>' \
  --form 'album_id=<string>' \
  --form ratings=2 \
  --form local_datetime_after=2023-11-07T05:31:56Z \
  --form local_datetime_before=2023-11-07T05:31:56Z \
  --form 'center=<string>' \
  --form radius=123 \
  --form 'bbox=<string>' \
  --form page=1 \
  --form limit=20 \
  --form image.0='@example-file'

import requests

url = "https://api.gumnut.ai/api/search"

files = { "image.0": ("example-file", open("example-file", "rb")) }
payload = {
    "library_id": "<string>",
    "query": "<string>",
    "image": "<string>",
    "person_ids": "<string>",
    "album_id": "<string>",
    "ratings": "2",
    "local_datetime_after": "2023-11-07T05:31:56Z",
    "local_datetime_before": "2023-11-07T05:31:56Z",
    "center": "<string>",
    "radius": "123",
    "bbox": "<string>",
    "page": "1",
    "limit": "20"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('library_id', '<string>');
form.append('query', '<string>');
form.append('image', '<string>');
form.append('person_ids', '<string>');
form.append('album_id', '<string>');
form.append('ratings', '2');
form.append('local_datetime_after', '2023-11-07T05:31:56Z');
form.append('local_datetime_before', '2023-11-07T05:31:56Z');
form.append('center', '<string>');
form.append('radius', '123');
form.append('bbox', '<string>');
form.append('page', '1');
form.append('limit', '20');
form.append('image.0', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.gumnut.ai/api/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumnut.ai/api/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumnut.ai/api/search"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gumnut.ai/api/search")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gumnut.ai/api/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"person_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"album_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ratings\"\r\n\r\n2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_after\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"local_datetime_before\"\r\n\r\n2023-11-07T05:31:56Z\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"center\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"radius\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bbox\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"limit\"\r\n\r\n20\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "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",
        "kind": "<string>",
        "current_version_id": "<string>",
        "file_size_bytes": 123,
        "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": {},
            "source": "automatic",
            "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",
        "stack_id": "<string>"
      },
      "distance": 123
    }
  ],
  "has_more": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

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

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.

Body

multipart/form-data

library_id

string | null

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

query

string | null

Natural-language search text, matched against image embeddings and authoritative metadata. Album and people names belong in album_id and person_ids, and date ranges in local_datetime_before/local_datetime_after, not here.

Maximum string length: 1000

image

file | null

Image file for an independent dense-image retrieval stage. When text is also provided, the stage ranks are fused rather than blending their embeddings.

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). Person IDs are carried by the entries of an asset's people field (returned with include=people).

album_id

string | null

Return only assets in this album — the album's album_ ID, not its name.

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

media_type

enum<string> | null

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

Available options:

image,

video

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.

page

integer

default:1

1-indexed page number; increment it to fetch subsequent pages. Stop when has_more is false, even if the current page is full. 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 (no content criterion) returns the full matching set newest-first, paginated without that cap.

Required range: x >= 1

limit

integer

default:20

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

Required range: 1 <= x <= 200

Response

Successful Response

data

SearchResultItem · object[]

required

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.

Show child attributes

has_more

boolean

required

Whether another page remains in this search's result population. For content searches, this refers to the bounded ranked candidate population, not every potentially matching asset in the library. While true, increment page and repeat the same search criteria, filters, and limit.

oauth

assets

album-assets

albums

events

library-invitations

libraries

search

faces

people

api-keys

server

stacks

tasks

users

Search assets

Authorizations

Query Parameters

Body

Response