POST
/
v1
/
storage
/
upload
curl -X POST https://api.verbalisai.com/v1/storage/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "folder=documents/contracts" \
  -F "public=false"

{
  "success": true,
  "data": {
    "file": {
      "id": "file_1234567890",
      "key": "user123/documents/contracts/document_1234567890.pdf",
      "original_name": "document.pdf",
      "size": 2048576,
      "mime_type": "application/pdf",
      "public": false,
      "folder": "documents/contracts",
      "uploaded_at": "2024-01-15T10:30:00Z",
      "metadata": {
        "project": "Client Project A",
        "category": "contract"
      },
      "urls": {
        "download": "https://api.verbalisai.com/v1/storage/file/user123/documents/contracts/document_1234567890.pdf",
        "direct": null
      },
      "checksums": {
        "md5": "5d41402abc4b2a76b9719d911017c592",
        "sha256": "7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
      }
    },
    "upload_info": {
      "processing_time": 1.2,
      "storage_region": "auto",
      "compression_applied": false
    }
  }
}
Upload a file to Cloudflare R2 storage with automatic organization and metadata extraction.
This endpoint requires API key authentication.
​
file
file
required
File to upload (supports various formats, max 1GB)
​
folder
string
Custom folder path for organization (e.g., “audio/recordings”)
​
public
boolean
default:"false"
Whether the file should be publicly accessible
​
metadata
object
Custom metadata to attach to the file
curl -X POST https://api.verbalisai.com/v1/storage/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "folder=documents/contracts" \
  -F "public=false"

{
  "success": true,
  "data": {
    "file": {
      "id": "file_1234567890",
      "key": "user123/documents/contracts/document_1234567890.pdf",
      "original_name": "document.pdf",
      "size": 2048576,
      "mime_type": "application/pdf",
      "public": false,
      "folder": "documents/contracts",
      "uploaded_at": "2024-01-15T10:30:00Z",
      "metadata": {
        "project": "Client Project A",
        "category": "contract"
      },
      "urls": {
        "download": "https://api.verbalisai.com/v1/storage/file/user123/documents/contracts/document_1234567890.pdf",
        "direct": null
      },
      "checksums": {
        "md5": "5d41402abc4b2a76b9719d911017c592",
        "sha256": "7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
      }
    },
    "upload_info": {
      "processing_time": 1.2,
      "storage_region": "auto",
      "compression_applied": false
    }
  }
}

​
Response Fields

​
file
object

​
Supported File Types

​
File Organization

Files are automatically organized using the following structure: 
/{user_id}/{folder}/{filename_with_timestamp}.{extension}

​
Rate Limits

  • 20 uploads per 15 minutes per IP address
  • 1GB maximum file size
  • 10GB total storage per free account

​
Notes

  • Files are stored redundantly across multiple regions
  • Automatic virus scanning is performed on all uploads
  • Private files require authentication to access
  • Public files get a direct CDN URL for fast access
  • Metadata is searchable through the file listing endpoints
  • Checksums are calculated for integrity verification