Skip to main content
POST
/
api
/
upload
Upload file
curl --request POST \
  --url https://api.example.com/api/upload \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "message": "<string>",
  "file": {
    "id": {},
    "name": "<string>",
    "location": "<string>",
    "user_id": {},
    "size": {},
    "public": true,
    "created_at": {}
  },
  "error": "<string>"
}

​
Authentication

This endpoint requires Bearer token authentication. 
Authorization: Bearer YOUR_JWT_TOKEN

​
Request

​
file
file
required
The file to upload. Must be sent as multipart/form-data.

​
Quota Validation

The endpoint performs automatic validation before accepting uploads:
  1. File Count Limit - Checks current file count against user’s max_files quota
  2. Storage Limit - Validates that file size + current usage doesn’t exceed max_storage
  3. Duplicate Check - Prevents uploading files with existing names in user’s directory
Files are uploaded to /app/data/uploads/{username}/ and stored with the original filename. If a file with the same name exists, the upload will be rejected with a 409 Conflict error.

​
Response

​
message
string
Success confirmation message
​
file
object
The created file record
​
id
uint
Unique file identifier
​
name
string
Original filename
​
location
string
Relative path: {username}/{filename}
​
user_id
uint
ID of the file owner
​
size
int64
File size in bytes
​
public
boolean
Public access flag (defaults to false)
​
created_at
timestamp
File creation timestamp

​
Error Responses

​
error
string
Error message describing the failure

​
400 Bad Request

{
  "error": "No file provided"
}

​
401 Unauthorized

{
  "error": "User not authenticated"
}

​
403 Forbidden - File Limit Exceeded

{
  "error": "File limit exceeded",
  "current_files": 100,
  "max_files": 100
}

​
403 Forbidden - Storage Limit Exceeded

{
  "error": "Storage limit exceeded",
  "current_storage": 5242880000,
  "max_storage": 5368709120,
  "file_size": 209715200
}

​
409 Conflict

{
  "error": "A file with this name already exists in your folder"
}

​
500 Internal Server Error

{
  "error": "Failed to save file"
}
Other possible 500 errors:
  • "Failed to get user information"
  • "Failed to check current file count"
  • "Failed to check current storage usage"
  • "Failed to create user directory"
  • "Failed to record file in database"

​
Examples

curl -X POST https://api.defdrive.com/api/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "file=@/path/to/document.pdf"

​
Success Response Example

{
  "message": "File uploaded successfully",
  "file": {
    "id": 42,
    "name": "document.pdf",
    "location": "johndoe/document.pdf",
    "user_id": 15,
    "size": 2048576,
    "public": false,
    "created_at": "2026-03-04T10:30:00Z",
    "updated_at": "2026-03-04T10:30:00Z"
  }
}
All uploaded files are set to private (public: false) by default. Use the Toggle Access endpoint to make files public.

Build docs developers (and LLMs) love

Get started for freeTalk to us