Upload Files

Endpoint

POST /upload

Auth: API Key, session, or a presigned signature from Sign Upload Content-Type: multipart/form-data

Form fields

file[]

required

One or more files to upload. Each file is validated for type and size.Allowed types: JPEG, PNG, WebP, AVIF, GIF, HEIC/HEIF, PSD, MP4, MOV, WebM, WAV, MP3, OGG, GLB, glTFMax size per file: Configurable via MAX_FILE_SIZE_MB (default: 50 MB)

HEIC/HEIF files are transcoded to JPEG on upload. The returned filename, path, and url will have a .jpg extension instead of the original .heic/.heif.

Content is checked, not just the extension. The first bytes of each file must match the format it claims to be, so a .jpg holding an HTML document or a .glb holding an arbitrary binary is rejected here rather than stored. A mismatch fails that one file with File content does not match its .jpg type and the rest of the batch still uploads.This matters because delivery serves stored bytes as they are, with nosniff and no content sniffing. Upload is where the type is decided, which is why it is strict.

string

Destination folder path within storage. Nested folders are supported.photos · uploads/2024/januaryIf omitted, files are stored at the root.

string[]

Custom filenames for each uploaded file, in the same order as files. If omitted, the original filename is used.Must include the file extension.

string[]

Transformation segments to prewarm (pre-generate and cache) immediately after upload. Supports up to 20 variants.w_800,h_600,c_fill · w_400,f_webp,q_85Pre-warming ensures the first user request is served from cache without any processing delay.

Response

200, All files uploaded successfully 207, Partial success (some files failed) 400, Validation error (invalid type, size exceeded, etc.) A fully successful upload returns only success and files. There is no errors key, and the optional per-file arrays appear only when they have something in them:

{
  "success": true,
  "files": [
    {
      "filename": "photo.jpg",
      "path": "photos/photo.jpg",
      "size": 204800,
      "url": "/t/photos/photo.jpg",
      "prewarmedUrls": ["/t/w_800,h_600,c_fill/photos/photo.jpg"]
    }
  ]
}

boolean

true if at least one file was processed. On a 207 this is still true, so check errors rather than success to detect partial failure.

array

Successfully uploaded files.

Show File object

string

Original or custom filename. A HEIC or HEIF upload is converted to JPEG, so this comes back with a .jpg extension.

string

Storage path relative to root.

number

File size in bytes, after any conversion.

string

Root-relative delivery path, always starting with /t/. Prefix it with your instance origin to get an absolute URL.

string[]

Image transformation paths that were generated and cached during the upload. Omitted when empty.

string[]

Prewarm failures. The file still uploaded successfully. Omitted when empty.

string[]

Video transformation paths queued for background processing. Omitted when empty.

string[]

Queue submission errors. Omitted when empty.

array

Files that failed to upload. Present only on a 207 or a 400.

Show Error object

string

Name of the failed file.

string

Error message.

Examples

Single file
Upload to folder
Upload with prewarm
Multiple files with custom names

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg"

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg" \
  -F "folder=products/2024"

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg" \
  -F "folder=photos" \
  -F "transformations=w_800,h_600,c_fill,f_webp" \
  -F "transformations=w_400,h_400,c_fill,g_face"

Uploads the file and immediately generates two cached variants.

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@IMG_001.jpg" \
  -F "files=@IMG_002.jpg" \
  -F "names=hero-banner.jpg" \
  -F "names=thumbnail.jpg" \
  -F "folder=assets"

Create Folder

Create an empty folder in storage.

Upload & Cache Warming

Prewarm strategy guide.

Delete File

Remove a file and its cached variants.

Sign Upload

Let an untrusted client upload without your API key.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

Endpoint

Form fields

Response

Examples

Create Folder

Upload & Cache Warming

Delete File

Sign Upload

​Endpoint

​Form fields

​Response

​Examples

​Related

Create Folder

Upload & Cache Warming

Delete File

Sign Upload

Endpoint

Form fields

Response

Examples

Related