Skip to main content
Upload one or more files to Zipline. This endpoint accepts multipart form data and returns URLs for the uploaded files.

​
Endpoint

POST /api/upload

​
Authentication

Requires authentication via Bearer token in the Authorization header. 
Authorization: Bearer <your-token>

​
Request

​
Multipart Form Data

Send files as multipart/form-data with one or more file fields.

​
Headers

All upload options are configured via custom headers:
​
X-Zipline-Format
string
default:"random"
Filename format to use. Options: random, uuid, date, name, gfycat, random-words.
X-Zipline-Format: uuid
​
X-Zipline-Filename
string
Override the generated filename (without extension).
X-Zipline-Filename: my-custom-name
​
X-Zipline-File-Extension
string
Override the file extension.
X-Zipline-File-Extension: .png
​
X-Zipline-Domain
string
Override the return domain. Supports multiple domains separated by commas (randomly selected).
X-Zipline-Domain: files.example.com,cdn.example.com
​
X-Zipline-Deletes-At
string
Set file expiration. Accepts:
  • Human-readable duration: 1d, 7d, 30m, 2h
  • ISO date: date=2024-12-31T23:59:59Z
  • Never expire: never
X-Zipline-Deletes-At: 7d
If server has maxExpiration configured, requests exceeding this limit will be rejected.
​
X-Zipline-Password
string
Protect file with a password. Users must enter this password to view the file.
X-Zipline-Password: secret123
​
X-Zipline-Max-Views
number
Maximum number of views before file is deleted.
X-Zipline-Max-Views: 10
​
X-Zipline-Original-Name
boolean
default:"false"
Store the original filename for reference.
X-Zipline-Original-Name: true
​
X-Zipline-Folder
string
Upload to a specific folder ID.
X-Zipline-Folder: clx7g8kj30001...
Folder must allow uploads if uploading without authentication.
​
X-Zipline-Image-Compression-Percent
number
Compress images by the specified percentage (0-100). Only works for image files.
X-Zipline-Image-Compression-Percent: 80
​
X-Zipline-Image-Compression-Type
string
Image compression format. Options: webp, jpeg, png, avif.
X-Zipline-Image-Compression-Type: webp
Compression type must be supported by the server’s installed dependencies.
​
X-Zipline-No-Json
boolean
default:"false"
Return plain text URLs (comma-separated) instead of JSON response.
X-Zipline-No-Json: true

​
Response

​
JSON Response (default)

​
files
array
required
Array of uploaded file objects.
​
files[].id
string
required
Unique file identifier.
​
files[].name
string
required
Generated filename with extension.
​
files[].type
string
required
MIME type of the file.
​
files[].url
string
required
Full URL to access the file.
​
files[].removedGps
boolean
Whether GPS metadata was removed (if enabled in server config).
​
files[].compressed
object
Compression details if image was compressed.
​
files[].compressed.ext
string
New file extension after compression.
​
files[].compressed.mimetype
string
New MIME type after compression.
​
deletesAt
string
ISO 8601 timestamp when files will be deleted, or "never" if no expiration.
​
assumedMimetypes
boolean[]
Array indicating which files had assumed MIME types (if server has assumeMimetypes enabled).

​
Plain Text Response

When X-Zipline-No-Json: true is set, returns comma-separated URLs: 
https://files.example.com/abc123.png,https://files.example.com/def456.jpg

​
Examples

​
Basic Upload

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.png"

​
Upload with Expiration

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zipline-Deletes-At: 7d" \
  -F "file=@/path/to/document.pdf"

​
Upload with Compression

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zipline-Image-Compression-Type: webp" \
  -H "X-Zipline-Image-Compression-Percent: 80" \
  -F "file=@/path/to/photo.jpg"

​
Upload Multiple Files

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file1=@/path/to/image1.png" \
  -F "file2=@/path/to/image2.jpg" \
  -F "file3=@/path/to/document.pdf"

​
Password Protected Upload

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zipline-Password: secret123" \
  -H "X-Zipline-Max-Views: 10" \
  -F "file=@/path/to/sensitive.pdf"

​
Upload to Folder

curl -X POST https://your-zipline.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zipline-Folder: clx7g8kj30001abc123" \
  -F "file=@/path/to/file.txt"

​
Response Example

{
  "files": [
    {
      "id": "clx7g8kj30001abc123xyz",
      "name": "a8c3e9f2.png",
      "type": "image/png",
      "url": "https://files.example.com/a8c3e9f2.png",
      "removedGps": true
    },
    {
      "id": "clx7h9kl40002def456uvw",
      "name": "b7d4f0g3.webp",
      "type": "image/webp",
      "url": "https://files.example.com/b7d4f0g3.webp",
      "compressed": {
        "ext": ".webp",
        "mimetype": "image/webp"
      }
    }
  ],
  "deletesAt": "2024-12-31T23:59:59.000Z"
}

​
Error Responses

​
400 Bad Request

  • Invalid header values
  • Disabled file extension
  • Invalid filename characters
  • Unrecognized MIME type (when assumeMimetypes is enabled)

​
403 Forbidden

  • Folder not open for uploads

​
413 Payload Too Large

  • File exceeds maxFileSize limit
  • Upload would exceed user quota

​
Notes

Files are validated against the server’s disabledExtensions list. Check your server configuration for allowed file types.
GPS metadata is automatically removed from images if removeGpsMetadata is enabled in server configuration.
Partial uploads (chunked uploads) should use the /api/upload/partial endpoint instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us