Skip to main content

​
Overview

The Upload API allows you to upload files and generate secure download links with expiration, view limits, and password protection. Files are stored on the server and accessed through temporary secure links.

​
Basic File Upload

Upload a file and receive a download link:
1

Prepare the multipart request

Create a POST request to /api/links/upload with the file as multipart/form-data:
curl -X POST http://localhost:8080/api/links/upload \
  -F "file=@/path/to/document.pdf"
2

Receive the response

The API returns a 201 Created response:
{
  "shortCode": "xyz789",
  "accessUrl": "http://localhost:8080/l/xyz789",
  "expiresAt": null,
  "maxViews": null
}
3

Share the download link

When users access the accessUrl, the file will be downloaded with the original filename.

​
Request Parameters

The LinkUploadRequestDto accepts the following form fields:
ParameterTypeRequiredValidationDescription
filefileYesMust not be nullThe file to upload
expiresAtstring (ISO 8601)NoMust be a future date/timeWhen the download link should expire
maxViewsintegerNoMust be positiveMaximum number of downloads allowed
passwordstringNo-Optional password protection
All parameters except file are optional. The file is uploaded as multipart/form-data.

​
Advanced Examples

​
Upload with Expiration

Create a download link that expires after a specific date: 
curl -X POST http://localhost:8080/api/links/upload \
  -F "[email protected]" \
  -F "expiresAt=2026-03-31T23:59:59+00:00"

​
Limited Downloads

Allow only a certain number of downloads: 
curl -X POST http://localhost:8080/api/links/upload \
  -F "[email protected]" \
  -F "maxViews=10"
Once the view limit is reached, the link will automatically expire and cannot be accessed again.

​
Password-Protected Upload

Require a password for downloading: 
curl -X POST http://localhost:8080/api/links/upload \
  -F "[email protected]" \
  -F "password=SecurePass123"
Users will need to provide the password via the X-Link-Password header when accessing the link. See Password Protection for details.

​
Complete Example with All Options

Combine expiration, download limits, and password protection: 
curl -X POST http://localhost:8080/api/links/upload \
  -F "[email protected]" \
  -F "expiresAt=2026-12-31T23:59:59+00:00" \
  -F "maxViews=5" \
  -F "password=contract2026"

​
File Download Behavior

When a user accesses a file download link:
  1. The server validates access permissions (password, expiration, view count)
  2. If valid, the file is returned with Content-Disposition: attachment header
  3. The browser prompts the user to download the file with its original filename
  4. The view count is incremented

​
Example Download Request

curl -L http://localhost:8080/l/xyz789 \
  -H "X-Link-Password: contract2026" \
  -o downloaded-file.pdf
The -L flag tells curl to follow redirects. The -o flag specifies the output filename.

​
Error Handling

​
File Validation Errors

{
  "timestamp": "2026-03-04T14:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "file: must not be null",
  "path": "/api/links/upload"
}

​
File Not Found on Download

If the file was deleted from the server: 
{
  "timestamp": "2026-03-04T14:30:00Z",
  "status": 404,
  "error": "Not Found",
  "message": "File not found",
  "path": "/l/xyz789"
}

​
Access Denied Errors

See Password Protection and Link Expiration for access control error responses.

​
Storage Considerations

Check your server configuration for maximum file upload size. By default, Spring Boot allows up to 1MB. You may need to configure spring.servlet.multipart.max-file-size and spring.servlet.multipart.max-request-size for larger files.
Uploaded files are stored on the server until:
  • The link expires (if expiresAt is set)
  • The link is manually revoked
  • A cleanup process removes expired files
Plan your storage capacity accordingly.
Original filenames are preserved and returned in the Content-Disposition header during download. Ensure filenames don’t contain special characters that might cause issues.
Files are stored on the server filesystem. Ensure proper file system permissions are set to prevent unauthorized access. Consider encrypting sensitive files at rest.

​
Best Practices

  • Use expiration for all uploads: Set reasonable expiration times to prevent indefinite storage
  • Limit download counts: For sensitive files, use maxViews to control distribution
  • Validate file types: Implement client-side validation before upload to improve UX
  • Monitor storage usage: Track uploaded file sizes and implement cleanup policies
  • Use passwords for sensitive data: Always password-protect confidential documents
  • Communicate limits to users: Let users know expiration dates and download limits

​
Next Steps

Password Protection

Secure file downloads with passwords

Link Expiration

Configure when download links expire

Creating Links

Create links for external URLs

Revocation

Manually revoke download links

Build docs developers (and LLMs) love

Get started for freeTalk to us