Skip to main content

​
Endpoint

POST /upload
Auth: API Key required
Content-Type: multipart/form-data

​
Form fields

​
files
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, WebMMax size per file: Configurable via MAX_FILE_SIZE_MB (default: 50 MB)
​
folder
string
Destination folder path within storage. Nested folders are supported.photos · uploads/2024/januaryIf omitted, files are stored at the root.
​
names
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.
​
transformations
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.) 
{
  "success": true,
  "files": [
    {
      "filename": "photo.jpg",
      "path": "photos/photo.jpg",
      "size": 204800,
      "url": "http://localhost:3000/t/photos/photo.jpg",
      "prewarmedUrls": [
        "http://localhost:3000/t/w_800,h_600,c_fill/photos/photo.jpg"
      ],
      "prewarmErrors": [],
      "queuedTransformationUrls": [],
      "queueErrors": []
    }
  ],
  "errors": []
}
​
success
boolean
true if all files were processed without error.
​
files
array
Successfully uploaded files.
​
errors
array
Files that failed to upload.

​
Examples

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

Create Folder

Create an empty folder in storage.

Upload & Cache Warming

Prewarm strategy guide.

Delete File

Remove a file and its cached variants.