Upload File

Upload a file and get a public URL.

POST /v1/upload

Upload File

cURL

curl --request POST \
  --url https://api.example.com/v1/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "folder": "<string>",
  "private": true,
  "expires": "<string>"
}
'

200

{
  "id": "<string>",
  "url": "<string>",
  "name": "<string>",
  "folder": "<string>",
  "size": 123,
  "type": "<string>",
  "private": true,
  "expires_at": "<string>",
  "created_at": "<string>"
}

Upload a file to StashFyle. Returns file metadata including a public CDN URL (or null for private files).

Request

file · file · required

The file to upload. Max size depends on your plan (10MB-500MB).

folder · string

Optional folder path to organize files. Example: images/avatars

private · boolean · default: "false"

Set to true to make the file private (requires secret key). Private files need signed URLs to access.

expires · string

Auto-delete after this duration. Format: 1h, 7d, 30d. Omit for permanent storage.

Response

id · string · required

Unique file identifier. Example: f_abc123xyz

url · string

Public CDN URL. null for private files.

name · string · required

Original filename.

folder · string

Folder path, or null if uploaded to root.

size · integer · required

File size in bytes.

type · string

MIME type. Example: image/jpeg

private · boolean · required

Whether the file is private.

expires_at · string

ISO 8601 expiration timestamp, or null if permanent.

created_at · string · required

ISO 8601 creation timestamp.

Examples

Basic Upload

curl

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@photo.jpg"

Response

{
  "id": "f_abc123xyz",
  "url": "https://cdn.stashfyle.com/live/user_123/f_abc123xyz/photo.jpg",
  "name": "photo.jpg",
  "folder": null,
  "size": 248000,
  "type": "image/jpeg",
  "private": false,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Upload to Folder

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@avatar.png" \
  -F "folder=users/avatars"

Private File

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@document.pdf" \
  -F "private=true"

Response

{
  "id": "f_xyz789abc",
  "url": null,
  "name": "document.pdf",
  "private": true,
  ...
}

Auto-Expiring File

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@temp-report.pdf" \
  -F "expires=7d"

Response

{
  "id": "f_temp123",
  "expires_at": "2024-01-22T10:30:00Z",
  ...
}

Errors

Code	Status	Description
unauthorized	401	Invalid or missing API key
forbidden	403	Public key with invalid origin
bad_request	400	Missing file or invalid parameters
file_too_large	413	File exceeds plan limit
storage_limit_exceeded	413	Storage quota exceeded
grace_period	403	Account in grace period
rate_limit_exceeded	429	Too many requests