upload-file

Upload File

Sprint 3

Shared

Upload a file to MinIO/S3 storage with quota checking. Files are automatically assigned unique filenames to prevent overwrites.

Account Type & Use Case

Shared Endpoint

Storage APIs enable both Individual and Organization account users to upload files for use as data sources, supporting CSV, Excel, JSON, and other formats. Individual accounts use these endpoints within their personal organization, with files stored in user-specific folders and quota limits based on the Individual Plan. Organization accounts use the same endpoints but with organization-wide quota limits and the ability to share files across team members. Files are always user-scoped (users can only access their own files), but Organization accounts have higher quota limits and can use files across multiple workspaces.

Endpoint

POST /api/v1/storage/upload

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	multipart/form-data

Form Data

Field	Type	Required	Description
file	file	Yes	File to upload
path	string	No	Optional path prefix for the file (e.g., "data-sources/org-123/")
file_category	string	No	File category: data_source, profile_image, general (default: data_source)

Response

Success (201)

{
  "success": true,
  "data": {
    "file_path": "organizations/1/files/123/report_20241203_101500_abc123.csv",
    "file_name": "report.csv",
    "unique_file_name": "report_20241203_101500_abc123.csv",
    "size": 1024000,
    "content_type": "text/csv",
    "s3_uri": "s3://rivergen-storage/organizations/1/files/123/report_20241203_101500_abc123.csv",
    "storage_file_id": 1
  },
  "message": "File uploaded successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing authentication token
413	REQUEST_ENTITY_TOO_LARGE	Storage quota exceeded
500	INTERNAL_SERVER_ERROR	Failed to upload file

Features

• Automatic unique filename generation (timestamp + UUID)
• Quota checking before upload
• Organization-based file structure
• File metadata tracking
• Returns storage_file_id for use in data source creation
• Original filename preserved for display

Unique Filename Format

Files are automatically renamed to prevent overwrites:

• Format: {original_name}_{YYYYMMDD_HHMMSS}_{uuid8}.{ext}
• Example: report_20241203_101500_abc123.csv

File Organization

Files are stored in the following structure:

organizations/{organization_id}/files/{user_id}/{unique_filename}

Quota Checking

• Quota is checked before file upload
• Upload is rejected if quota would be exceeded
• Quota is updated automatically after successful upload

Example

curl -X POST "https://api.rivergen.com/api/v1/storage/upload" \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@report.csv" \
  -F "file_category=data_source"

Related Endpoints

• List Files - List uploaded files
• Get Usage - Check storage usage and quota
• Data Sources - Create - Use file_path to create data source