Skip to Content
IntroductionUploading Files

Uploading Files

Learn how to upload files using FileZen’s powerful file upload API, including support for small files, large files with chunked uploads, and streaming uploads.

đź’ˇ SDK Available: While this documentation shows direct API usage with cURL examples, most of these methods are also available in our SDKs for faster integration. Check out our frameworks section for available integrations and a more streamlined development experience.

Authentication

FileZen supports multiple authentication methods for file uploads:

API Key Authentication

Include your API key in the request headers:

curl -X POST "https://api.filezen.dev/files/upload" \
  -H "ApiKey: your-api-key-here"

Bearer Token Authentication

Use JWT tokens with the Authorization header:

curl -X POST "https://api.filezen.dev/files/upload" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-Project-Id: your-project-id"

Presigned URL Authentication

Generate presigned URLs for secure, temporary access without exposing credentials. See the Presigned URLs section for detailed examples.

Upload Methods

FileZen provides three main upload methods depending on your needs:

1. Single File Upload

For files smaller than 10MB, use the simple single file upload endpoint:

curl -X POST "https://api.filezen.dev/files/upload" \
  -H "ApiKey: your-api-key-here" \
  -H "X-Folder-Id: optional-parent-folder-id" \
  -F "file=@/path/to/your/file.jpg" \
  -F "name=my-uploaded-file.jpg" \
  -F "type=image/jpeg" \
  -F "metadata={\"description\":\"My uploaded image\"}"

Response:

{
  "id": "file-uuid",
  "createdAt": "2024-01-01T12:00:00Z",
  "updatedAt": "2024-01-01T12:00:00Z",
  "type": "file",
  "state": "completed",
  "name": "my-uploaded-file.jpg",
  "mimeType": "image/jpeg",
  "size": 1024000,
  "region": "us",
  "projectId": "project-uuid",
  "url": "https://cdn.filezen.dev/files/file-uuid"
}

2. Chunked Upload (Large Files)

For files larger than 10MB, use chunked uploads for better reliability and progress tracking:

Step 1: Initialize Chunked Upload

curl -X POST "https://api.filezen.dev/files/chunk-upload/initialize" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "large-file.mp4",
    "uploadMode": "chunked",
    "totalSize": 104857600,
    "mimeType": "video/mp4",
    "chunkSize": 10485760,
    "metadata": {"category": "videos"},
    "parentId": "optional-parent-folder-id"
  }'

Response:

{
  "id": "session-uuid",
  "fileName": "large-file.mp4",
  "totalSize": 104857600,
  "chunkSize": 10485760,
  "totalChunks": 10,
  "uploadedChunks": [],
  "uploadedSize": 0,
  "isComplete": false
}

Step 2: Upload Chunks

Upload each chunk sequentially:

# Upload chunk 0
curl -X POST "https://api.filezen.dev/files/chunk-upload/part" \
  -H "ApiKey: your-api-key-here" \
  -H "Chunk-Session-Id: session-uuid" \
  -H "Chunk-Index: 0" \
  -H "Chunk-Size: 10485760" \
  -F "chunk=@chunk-0.bin"
 
# Upload chunk 1
curl -X POST "https://api.filezen.dev/files/chunk-upload/part" \
  -H "ApiKey: your-api-key-here" \
  -H "Chunk-Session-Id: session-uuid" \
  -H "Chunk-Index: 1" \
  -H "Chunk-Size: 10485760" \
  -F "chunk=@chunk-1.bin"
 
# Continue for all chunks...

Chunk Upload Response:

{
  "sessionId": "session-uuid",
  "chunkIndex": 0,
  "uploaded": true,
  "nextChunkIndex": 1,
  "isComplete": false,
  "session": {
    "uploadedChunks": [0],
    "uploadedSize": 10485760
  }
}

Final Chunk Response (when complete):

{
  "sessionId": "session-uuid",
  "chunkIndex": 9,
  "uploaded": true,
  "isComplete": true,
  "file": {
    "id": "file-uuid",
    "name": "large-file.mp4",
    "size": 104857600,
    "url": "https://cdn.filezen.dev/files/file-uuid"
  }
}

3. Streaming Upload (Unknown Size)

For files with unknown size or real-time streaming:

Step 1: Initialize Streaming Upload

curl -X POST "https://api.filezen.dev/files/chunk-upload/initialize" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "stream-data.log",
    "uploadMode": "streaming",
    "mimeType": "text/plain",
    "metadata": {"source": "live-stream"}
  }'

Step 2: Upload Stream Chunks

# Upload stream chunks as they become available
curl -X POST "https://api.filezen.dev/files/chunk-upload/part" \
  -H "ApiKey: your-api-key-here" \
  -H "Chunk-Session-Id: session-uuid" \
  -H "Chunk-Size: 1048576" \
  -F "chunk=@stream-chunk-1.bin"
 
curl -X POST "https://api.filezen.dev/files/chunk-upload/part" \
  -H "ApiKey: your-api-key-here" \
  -H "Chunk-Session-Id: session-uuid" \
  -H "Chunk-Size: 2097152" \
  -F "chunk=@stream-chunk-2.bin"

Step 3: Complete Streaming Upload

curl -X POST "https://api.filezen.dev/files/chunk-upload/complete" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "session-uuid"}'

File Organization

Folder Structure

Organize files using folder IDs or path-based naming:

# Upload to specific folder
curl -X POST "https://api.filezen.dev/files/upload" \
  -H "ApiKey: your-api-key-here" \
  -H "X-Folder-Id: parent-folder-uuid" \
  -F "file=@document.pdf"
 
# Create or upload to existing nested folder structure with path
curl -X POST "https://api.filezen.dev/files/upload" \
  -H "ApiKey: your-api-key-here" \
  -F "file=@document.pdf" \
  -F "name=documents/2024/january/document.pdf"

Presigned URLs

Generate secure, temporary upload URLs that don’t require exposing API keys:

Generate Presigned URL

curl -X POST "https://api.filezen.dev/files/signed-url" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "my-file.jpg",
    "path": "/files/upload", // or "/files/chunk-upload/initialize" for multipart or streaming upload
    "expiresIn": 3600
  }'

Response:

{
  "url": "https://api.filezen.dev/files/upload?signature=abc123&accessKey=key123&expires=1704110400"
}

Upload with Presigned URL

curl -X POST "https://api.filezen.dev/files/upload?signature=abc123&accessKey=key123&expires=1704110400" \
  -F "file=@/path/to/file.jpg" \
  -F "name=my-file.jpg"

File Management

Get Upload Session Status

curl -X GET "https://api.filezen.dev/files/chunk-upload/session/session-uuid"

Cancel Upload Session

curl -X DELETE "https://api.filezen.dev/files/chunk-upload/cancel/session-uuid"

Delete File by URL

curl -X DELETE "https://api.filezen.dev/files/delete-by-url" \
  -H "ApiKey: your-api-key-here" \
  -G -d "url=https://cdn.filezen.dev/files/file-uuid"

Error Handling

Common error responses:

Authentication Errors

{
  "statusCode": 401,
  "message": "ApiKey not found",
  "error": "Unauthorized"
}

Validation Errors

{
  "statusCode": 400,
  "message": "Total size is required for chunked upload mode",
  "error": "Bad Request"
}

Session Errors

{
  "statusCode": 400,
  "message": "Upload session has expired",
  "error": "Bad Request"
}

Best Practices

File Size Recommendations

  • Small files (< 10MB): Use single file upload
  • Large files (> 10MB): Use chunked upload with 5-10MB chunks
  • Streaming data: Use streaming upload mode

Error Recovery

  • Chunked uploads are resumable - you can restart from the last successful chunk
  • Check session status before continuing uploads
  • Implement exponential backoff for retry logic

Performance Tips

  • Use appropriate chunk sizes (5-10MB for most cases)
  • Upload chunks in parallel when possible (client-side)
  • Set reasonable timeout values for large files
  • Monitor upload progress and provide user feedback

Security Considerations

  • Use presigned URLs for client-side uploads to avoid exposing API keys
  • Set appropriate expiration times for presigned URLs
  • Validate file types and sizes on both client and server
  • Implement rate limiting for upload endpoints

Metadata and File Types

Supported Metadata

You can include any custom data in JSON format:

{
  "metadata": {
    "description": "File description",
    "tags": ["tag1", "tag2"],
    "category": "documents",
    "customField": "custom value",
    "nested": {
      "property": "value"
    },
    "number": 123,
    "boolean": true
  }
}

MIME Type Detection

FileZen automatically detects MIME types, but you can specify them explicitly (e.g., image/jpeg, video/mp4, application/pdf, text/plain).

Regional Storage

Files are automatically stored in the appropriate region based on your project configuration. The CDN ensures fast global delivery regardless of storage location.

Last updated on
AboutWorking with Files
© 2026 FileZen. All rights reserved.