Storage API Documentation
Complete API reference for the Storage Box system
Authentication
Most API endpoints require authentication. Include the Firebase ID token in the Authorization header:
Authorization: Bearer <firebase_id_token>
Storage Boxes
GET /api/storage/boxes
GETGet all storage boxes for the authenticated user
Query Parameters:
view_all=true - Admin only: View all users' storage boxes
Response:
{
"boxes": [
{
"id": 1,
"name": "Project Files",
"description": "Important project documents",
"share_token": "abc123def456",
"location": "Finland, Turku",
"drive_name": "box1-drive1",
"current_storage_bytes": 1048576,
"max_storage_bytes": 2147483648,
"is_locked": false,
"created_at": "2024-01-15T10:30:00Z"
}
],
"is_admin": false
}POST /api/storage/boxes
POSTCreate a new storage box
Request Body:
{
"name": "My Storage Box",
"description": "Optional description"
}Response:
{
"success": true,
"box": {
"id": 2,
"name": "My Storage Box",
"description": "Optional description",
"share_token": "xyz789uvw012",
"location": "Finland, Turku",
"drive_name": "box1-drive1",
"current_storage_bytes": 0,
"max_storage_bytes": 2147483648,
"is_locked": false,
"created_at": "2024-01-15T11:00:00Z"
}
}PUT /api/storage/boxes/{box_id}
PUTUpdate storage box details
Request Body:
{
"name": "Updated Box Name",
"description": "Updated description"
}Response:
{
"success": true
}DELETE /api/storage/boxes/{box_id}
DELETEDelete a storage box and all its files
Response:
{
"success": true
}File Management
POST /api/storage/upload
POSTUpload files to a storage box
Request:
multipart/form-data
box_id(integer) - Target storage box IDfiles(file[]) - Files to upload (multiple files supported)
Response:
{
"success": true,
"uploaded": [
{
"id": 123,
"filename": "document.pdf",
"original_filename": "my-document.pdf",
"size_bytes": 1048576,
"mime_type": "application/pdf",
"uploaded_at": "2024-01-15T12:00:00Z"
}
]
}DELETE /api/storage/files/{file_id}
DELETEDelete a file from storage
Response:
{
"success": true
}GET /api/storage/files/{file_id}/download
GETDownload a file from storage
Response:
Binary file data with appropriate Content-Type and Content-Disposition headers
Sharing
GET /api/storage/share/{share_token}
GETGet shared storage box details (public access)
Response:
{
"box": {
"id": 1,
"name": "Shared Files",
"description": "Publicly accessible files",
"is_locked": false,
"created_at": "2024-01-15T10:30:00Z"
},
"files": [
{
"id": 123,
"filename": "public-document.pdf",
"original_filename": "document.pdf",
"size_bytes": 1048576,
"mime_type": "application/pdf",
"uploaded_at": "2024-01-15T12:00:00Z"
}
]
}GET /api/storage/share/{share_token}/files/{file_id}/download
GETDownload a file from a shared storage box (public access)
Response:
Binary file data with appropriate Content-Type and Content-Disposition headers
GET /api/storage/file/{file_share_token}
GETGet shared file details (public access)
Response:
{
"file": {
"id": 123,
"filename": "shared-file.pdf",
"original_filename": "important-document.pdf",
"size_bytes": 1048576,
"mime_type": "application/pdf",
"uploaded_at": "2024-01-15T12:00:00Z"
}
}GET /api/storage/file/{file_share_token}/download
GETDownload a shared file (public access)
Response:
Binary file data with appropriate Content-Type and Content-Disposition headers
Error Responses
Common Error Format:
{
"success": false,
"error": "Error message description"
}
401
Unauthorized - Invalid or missing authentication token
403
Forbidden - Access denied to resource
404
Not Found - Resource does not exist
413
Payload Too Large - File exceeds size limit
500
Internal Server Error - Server-side error occurred
Rate Limiting
Rate limits apply to all endpoints. Current limits:
- • Upload requests: 10 per minute per user
- • Download requests: 60 per minute per IP
- • Other requests: 100 per minute per user
When rate limited, HTTP 429 is returned with Retry-After header.
Code Examples
JavaScript (Fetch API)
// Get authentication token from Firebase
const user = firebase.auth().currentUser;
const token = await user.getIdToken();
// Get storage boxes
const response = await fetch('/api/storage/boxes', {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
// Upload a file
const formData = new FormData();
formData.append('box_id', '1');
formData.append('files', fileInput.files[0]);
const uploadResponse = await fetch('/api/storage/upload', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: formData
});
const uploadData = await uploadResponse.json();Python (requests)
import requests
# Your Firebase ID token
auth_token = "your_firebase_id_token"
headers = {
'Authorization': f'Bearer {auth_token}',
'Content-Type': 'application/json'
}
# Get storage boxes
response = requests.get('https://your-domain.com/api/storage/boxes', headers=headers)
boxes = response.json()
# Upload a file
upload_headers = {
'Authorization': f'Bearer {auth_token}'
}
with open('document.pdf', 'rb') as f:
files = {'files': f}
data = {'box_id': '1'}
upload_response = requests.post(
'https://your-domain.com/api/storage/upload',
headers=upload_headers,
files=files,
data=data
)
result = upload_response.json()