Skip to main content

​
Overview

DefDrive allows you to securely upload files to your personal storage space. Each upload is validated against your storage quota and file limits to ensure you stay within your allocated resources.

​
Prerequisites

Before uploading files, ensure you have:
  • A valid authentication token
  • Sufficient storage quota available
  • Not exceeded your maximum file count limit

​
Storage Limits

Default user limits:
  • Maximum files: 100 files
  • Maximum storage: 1 GB (1,073,741,824 bytes)
These limits can be viewed and are enforced at upload time. See models/user.go:14-15 for default values.

​
Upload Process

1

Authenticate your request

Include your authentication token in the request headers. The system validates your identity before processing the upload.
2

Prepare your file

Ensure your file doesn’t exceed remaining storage quota. The system checks both file count and total storage usage.
3

Send upload request

Use multipart form data to upload your file to the /api/upload endpoint.
4

Verify upload

Receive confirmation with file metadata including ID, name, location, and size.

​
API Request Examples

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

​
Success Response

When a file is successfully uploaded, you’ll receive a response like: 
{
  "message": "File uploaded successfully",
  "file": {
    "ID": 42,
    "CreatedAt": "2026-03-04T10:30:00Z",
    "UpdatedAt": "2026-03-04T10:30:00Z",
    "DeletedAt": null,
    "Name": "document.pdf",
    "Location": "johndoe/document.pdf",
    "Size": 2048576,
    "Hash": "",
    "Public": false,
    "UserID": 7
  }
}

​
Error Responses

​
Storage Quota Exceeded

When you don’t have enough storage space: 
{
  "error": "Storage limit exceeded",
  "current_storage": 950000000,
  "max_storage": 1073741824,
  "file_size": 150000000
}
The upload will fail if current_storage + file_size > max_storage. Check your available space before uploading large files.

​
File Count Limit Exceeded

When you’ve reached your maximum file count: 
{
  "error": "File limit exceeded",
  "current_files": 100,
  "max_files": 100
}

​
Duplicate File Name

When a file with the same name already exists in your directory: 
{
  "error": "A file with this name already exists in your folder"
}
Rename your file locally before uploading, or delete the existing file first. File names must be unique within your user directory.

​
File Storage Location

Files are stored in a user-specific directory structure: 
/app/data/uploads/
└── username/
    ├── document.pdf
    ├── image.png
    └── report.xlsx
The Location field in the database stores the relative path: username/filename.ext (see controllers/file.go:102).

​
Checking Your Storage Usage

Before uploading, you can check your current usage: 
curl -X GET https://your-defdrive-instance.com/files/stats \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
Response: 
{
  "file_count": 45,
  "total_storage": 523456789,
  "file_types": [
    {
      "extension": "pdf",
      "count": 12,
      "total_size": 204800000
    },
    {
      "extension": "png",
      "count": 20,
      "total_size": 150000000
    }
  ]
}

​
Implementation Details

The upload process performs the following validations (see controllers/file.go:24-122):
  1. Authentication check - Validates user session
  2. File count check - Ensures user hasn’t exceeded MaxFiles limit
  3. Storage check - Calculates current storage and validates new file fits within MaxStorage
  4. Directory creation - Creates user directory if it doesn’t exist
  5. Duplicate check - Prevents overwriting existing files
  6. File save - Saves file to disk and creates database record
All files are initially uploaded as private (Public: false). Use the toggle public access endpoint to make files publicly accessible.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us