Upload a new asset

curl --request POST \
  --url https://api.gumnut.ai/api/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form asset_data='@example-file' \
  --form device_asset_id=IMG_0421 \
  --form device_id=teds-iphone \
  --form 'file_created_at=2026-05-04T10:30:00+10:00' \
  --form 'file_modified_at=2026-05-04T10:30:00+10:00' \
  --form library_id=lib_2c6ihMLYJUt3vctZWi9SNP

import requests

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

files = { "asset_data": ("example-file", open("example-file", "rb")) }
payload = {
    "device_asset_id": "IMG_0421",
    "device_id": "teds-iphone",
    "file_created_at": "2026-05-04T10:30:00+10:00",
    "file_modified_at": "2026-05-04T10:30:00+10:00",
    "library_id": "lib_2c6ihMLYJUt3vctZWi9SNP"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('asset_data', '<string>');
form.append('device_asset_id', 'IMG_0421');
form.append('device_id', 'teds-iphone');
form.append('file_created_at', '2026-05-04T10:30:00+10:00');
form.append('file_modified_at', '2026-05-04T10:30:00+10:00');
form.append('library_id', 'lib_2c6ihMLYJUt3vctZWi9SNP');

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

options.body = form;

fetch('https://api.gumnut.ai/api/assets', 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/assets",
  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=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\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/assets"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\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/assets")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\r\n-----011000010111000001101001--"

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

{
  "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_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",
  "stack_id": "<string>"
}

{
  "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_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",
  "stack_id": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

assets

Upload a new asset

Uploads a new asset (image or video) and its metadata as multipart form data, returning the created asset with 201. Uploads are deduplicated per library by the file’s SHA-256 checksum: re-uploading a file whose bytes already exist in the target library stores nothing and returns the existing asset with 200. Storage caps are checked before the duplicate lookup, so an upload is refused with 507 whenever the account or the target library is already at its storage cap — even when the bytes would have deduplicated to an existing asset. A transient upstream storage error returns 502 — retryable after the Retry-After interval. When library_id is omitted and no default library can be chosen (the account has multiple live libraries), the request is refused with 400. Image metadata is extracted before the response returns; the rest of processing (thumbnails, search indexing, face detection, and video metadata extraction) continues asynchronously after the response.

POST

api

assets

Upload a new asset

curl --request POST \
  --url https://api.gumnut.ai/api/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form asset_data='@example-file' \
  --form device_asset_id=IMG_0421 \
  --form device_id=teds-iphone \
  --form 'file_created_at=2026-05-04T10:30:00+10:00' \
  --form 'file_modified_at=2026-05-04T10:30:00+10:00' \
  --form library_id=lib_2c6ihMLYJUt3vctZWi9SNP

import requests

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

files = { "asset_data": ("example-file", open("example-file", "rb")) }
payload = {
    "device_asset_id": "IMG_0421",
    "device_id": "teds-iphone",
    "file_created_at": "2026-05-04T10:30:00+10:00",
    "file_modified_at": "2026-05-04T10:30:00+10:00",
    "library_id": "lib_2c6ihMLYJUt3vctZWi9SNP"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('asset_data', '<string>');
form.append('device_asset_id', 'IMG_0421');
form.append('device_id', 'teds-iphone');
form.append('file_created_at', '2026-05-04T10:30:00+10:00');
form.append('file_modified_at', '2026-05-04T10:30:00+10:00');
form.append('library_id', 'lib_2c6ihMLYJUt3vctZWi9SNP');

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

options.body = form;

fetch('https://api.gumnut.ai/api/assets', 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/assets",
  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=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\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/assets"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\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/assets")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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=\"asset_data\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_asset_id\"\r\n\r\nIMG_0421\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"device_id\"\r\n\r\nteds-iphone\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_created_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_modified_at\"\r\n\r\n2026-05-04T10:30:00+10:00\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"library_id\"\r\n\r\nlib_2c6ihMLYJUt3vctZWi9SNP\r\n-----011000010111000001101001--"

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

{
  "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_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",
  "stack_id": "<string>"
}

{
  "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_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",
  "stack_id": "<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.

Body

multipart/form-data

asset_data

file

required

The image or video file, sent as a binary multipart part with a filename. The file's MIME type is derived from the filename extension and must be an image or video type; files with an unrecognized or non-media extension are rejected with 422. The filename is stored as the asset's original file name (maximum 1024 characters). The API imposes no fixed per-file size limit; uploads are constrained only by the storage caps.

device_asset_id

string

required

Identifier of this asset on the uploading device, chosen by the client (for example, the device's local asset ID). Stored verbatim and usable for device-based existence checks; plays no part in upload-time duplicate detection.

Example:

"IMG_0421"

device_id

string

required

Identifier of the uploading device or client, chosen by the client. Paired with device_asset_id for device-based existence checks.

Example:

"teds-iphone"

file_created_at

string<date-time>

required

When the file was created on the uploading device, as an ISO 8601 datetime. Also serves as the fallback for the asset's local capture time when the file's embedded metadata carries no usable timestamp.

Example:

"2026-05-04T10:30:00+10:00"

file_modified_at

string<date-time>

required

When the file was last modified on the uploading device, as an ISO 8601 datetime.

Example:

"2026-05-04T10:30:00+10:00"

library_id

string | null

Library to upload into. For an all-library credential, omit to use the account's sole live library or create a fresh default when there are no live libraries; pass explicitly when the account has multiple live libraries. For a selected-library credential, omit to use its sole selected library; pass explicitly when it selects multiple libraries.

Example:

"lib_2c6ihMLYJUt3vctZWi9SNP"

Response

The file already exists in the target library (matched by SHA-256 checksum); the existing asset is returned and nothing new is stored.

Represents a photo or video asset with metadata and access URLs.

Top-level fields describe the asset's current rendering (the version identified by current_version_id) unless they explicitly name the original upload, like original_file_name and the file_data group.

string

required

Unique asset identifier with 'asset_' prefix

mime_type

string

required

MIME type of the current rendering (e.g., 'image/jpeg', 'video/mp4').

original_file_name

string

required

Filename the asset was uploaded under.

local_datetime

string<date-time>

required

When the photo/video was taken, in the device's local timezone

created_at

string<date-time>

required

When this asset record was created in the database

updated_at

string<date-time>

required

When this asset record was last updated

kind

string

required

What produced the current rendering: original (the upload), edit (a client-baked edit), or external:<service>. The namespace is open — derive edited-ness as kind != "original".

current_version_id

string

required

ID (asset_version_ prefix) of the current version, which the top-level rendering fields describe. Pass it as the expected current version on version writes so a racing write is rejected.

file_data

FileDataResponse · object | null

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

Show child attributes

metadata

MetadataResponse · object | null

Asset metadata — camera/EXIF fields, GPS, and location names. null when not requested via include=metadata.

Show child attributes

metrics

Metrics · object | null

ML-generated quality scores and other metrics. null when not requested via include=metrics.

Show child attributes

asset_urls

Asset Urls · object | null

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 (, fetch) still render it. Variant URLs are stable: a derived variant may briefly 404 until its artifact is generated, then serve from the same URL.

Show child attributes

description

string | null

AI-generated description of the asset's content, quality, and composition. null means description generation has not yet run; empty string means the model refused to describe the asset. Distinct from metadata.description (camera-embedded EXIF metadata).

thumbhash

string | null

Base64-encoded ThumbHash placeholder (~28 chars). Clients decode with the thumbhash library (JS / Swift / Kotlin) to render an instant blurred preview before the CDN thumbnail arrives. null while generation is pending.

faces

FaceResponse · object[] | null

All faces detected in this asset. null when not requested via include=faces; [] when requested but the asset has no faces.

Show child attributes

people

PersonResponse · object[] | null

All unique people identified in this asset (deduplicated from faces). null when not requested via include=people; [] when requested but none are identified.

Show child attributes

width

integer

default:0

Width of the current rendering in pixels.

height

integer

default:0

Height of the current rendering in pixels.

duration

number | null

Video length in seconds. null for images and for videos whose duration has not been extracted yet.

trashed_at

string<date-time> | null

When this asset was moved to trash (ISO 8601, UTC). null for live assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window.

stack_id

string | null

ID of the stack this asset belongs to (asset_stack_ prefix), or null when the asset is not part of a stack. Group assets by this value to collapse a stack into a single tile; the stack's own cover and member count are not carried on the asset. Distinct from metadata.auto_stack_id, which is the camera's in-EXIF MakerNotes:AutoStackID string — this is the server-assigned foreign key to the asset's stack.

oauth

assets

album-assets

albums

events

libraries

search

faces

people

api-keys

server

stacks

tasks

users

Upload a new asset

Authorizations

Body

Response