Skip to main content
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

MP3, WAV, FLAC, M4A, OGG, WEBM, AAC
MP4, AVI, MOV, WMV, MKV, WEBM
PDF, DOC, DOCX, TXT, RTF, ODT
JPG, PNG, GIF, WEBP, SVG, BMP, TIFF
JSON, XML, CSV, XLSX, ZIP, TAR, GZ

​
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
⌘I