Skip to main content
POST
/
api
/
assets
Upload a new asset
curl --request POST \
  --url https://api.example.com/api/assets \
  --header 'Content-Type: multipart/form-data' \
  --form asset_data='@example-file' \
  --form 'device_asset_id=<string>' \
  --form 'device_id=<string>' \
  --form file_created_at=2023-11-07T05:31:56Z \
  --form file_modified_at=2023-11-07T05:31:56Z \
  --form 'library_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",
  "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"
}

Body

multipart/form-data
​
asset_data
file
required

The asset file to upload

​
device_asset_id
string
required
​
device_id
string
required
​
file_created_at
string<date-time>
required
​
file_modified_at
string<date-time>
required
​
library_id
string | null

Library to upload asset to (optional)

Response

Successful Response

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

​
id
string
required

Unique asset identifier with 'asset_' prefix

​
mime_type
string
required

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

​
original_file_name
string
required

Original filename when the asset was uploaded

​
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

​
file_data
FileDataResponse · object

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

​
metadata
MetadataResponse · object

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

​
metrics
Metrics · object

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

​
asset_urls
Asset Urls · object

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

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

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

​
width
integer
default:0

Width of the asset in pixels

​
height
integer
default:0

Height of the asset 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.