Upload File

Upload a file to your storage

POST /api/v1/files/upload

cURL

curl -X POST "https://api.fileguard.io/api/v1/files/upload" \
  -H "Authorization: Bearer fg_your_api_key" \
  -F "file=@/path/to/document.pdf" \
  -F "context=patient_reports"

201 Created

{
  "status": "SUCCESS",
  "message": "File uploaded successfully",
  "data": {
    "file_id": "file_z1x2c3v4b5n6",
    "original_filename": "blood_test.pdf",
    "content_type": "application/pdf",
    "size_bytes": 245678,
    "context_key": "patient_reports"
  },
  "timestamp": "2026-01-04T10:00:00Z"
}

Upload a file to the tenant’s S3 storage within a specified file context.

Request

file · binary · required

The file to upload

context · string · required

File context key (e.g., patient_reports, invoices)

Validation

Before storing, FileGuard validates the file:

1. Extension Check - Must be in context’s allowed_extensions
2. Size Check - Must not exceed context’s max_file_size_mb
3. Blank File Detection - Rejects empty/blank files (if reject_blank_files is enabled)
4. Corrupt File Detection - Validates file integrity (if reject_corrupt_files is enabled)
5. Virus Scan - Scans for malware using ClamAV (if scan_for_viruses is enabled)

Response

status · string

SUCCESS or ERROR

data · object

Show properties

file_id · string

Unique file identifier (e.g., file_z1x2c3v4b5n6)

original_filename · string

Original filename from upload

content_type · string

MIME type (e.g., application/pdf)

size_bytes · integer

File size in bytes

context_key · string

The file context key

cURL

curl -X POST "https://api.fileguard.io/api/v1/files/upload" \
  -H "Authorization: Bearer fg_your_api_key" \
  -F "file=@/path/to/document.pdf" \
  -F "context=patient_reports"

201 Created

{
  "status": "SUCCESS",
  "message": "File uploaded successfully",
  "data": {
    "file_id": "file_z1x2c3v4b5n6",
    "original_filename": "blood_test.pdf",
    "content_type": "application/pdf",
    "size_bytes": 245678,
    "context_key": "patient_reports"
  },
  "timestamp": "2026-01-04T10:00:00Z"
}

Required Scope

Requires upload scope on your API key.

Rate Limiting

Upload rate limits can be configured at both tenant and context levels. When exceeded, you’ll receive:

• HTTP 429 status code
• Retry-After header with seconds to wait
• X-RateLimit-Limit and X-RateLimit-Remaining headers

Storage Quotas

If your tenant or context has a storage quota configured, uploads that would exceed the quota are rejected with HTTP 400.