> ## Documentation Index
> Fetch the complete documentation index at: https://backdrift.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Storage

> Upload, store, and serve files securely.

Backdrift provides secure file storage for uploads like profile pictures, documents, and attachments.

## Defining Storage

Describe what files you need to store:

```
"Users can upload profile pictures."
```

```
"Tasks can have file attachments (PDFs, images, documents)."
```

```
"Products have multiple gallery images."
```

## How It Works

```mermaid theme={null}
graph LR
    A[Client] --> B[Get Upload URL]
    B --> C[Upload to Storage]
    C --> D[Save Reference]
    D --> E[Retrieve File]
```

1. Client requests a **signed upload URL**
2. Client uploads directly to storage (not through your API)
3. Client saves the file reference to the entity
4. Files are retrieved via signed URLs or CDN

## Upload Flow

### 1. Request Upload URL

```bash theme={null}
POST /v1/tasks/{taskId}/attachments/upload-url
{
  "filename": "report.pdf",
  "contentType": "application/pdf"
}
```

Response:

```json theme={null}
{
  "uploadUrl": "https://s3.amazonaws.com/bucket/...",
  "fileKey": "attachments/task-123/report.pdf",
  "expiresIn": 3600
}
```

### 2. Upload File

```bash theme={null}
curl -X PUT "${uploadUrl}" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
```

### 3. Save Reference

```bash theme={null}
PATCH /v1/tasks/{taskId}
{
  "attachment_key": "attachments/task-123/report.pdf"
}
```

## Download Flow

### Get Signed URL

```bash theme={null}
GET /v1/tasks/{taskId}/attachments/{fileKey}/download-url
```

Response:

```json theme={null}
{
  "downloadUrl": "https://s3.amazonaws.com/bucket/...",
  "expiresIn": 3600
}
```

## File Restrictions

Configure allowed file types and sizes:

```
"Attachments can be PDFs, images, or documents up to 10MB."
```

```
"Profile pictures must be images under 2MB."
```

This generates:

* Content-type validation
* File size limits
* Optional virus scanning

## Storage Configuration

Backdrift configures storage with security best practices:

| Setting       | Default                    |
| ------------- | -------------------------- |
| Encryption    | Server-side (AES-256)      |
| Versioning    | Disabled                   |
| Public access | Blocked                    |
| CORS          | Configured for your domain |
| Lifecycle     | No automatic deletion      |

## Lifecycle Policies

Configure automatic cleanup:

```
"Delete attachments 90 days after the task is completed."
```

```
"Move old files to cheaper storage after 30 days."
```

## CDN (Optional)

For public files (like product images), enable CDN:

```
"Product images should be served from a CDN for fast loading."
```

This creates a CloudFront distribution with:

* Global edge caching
* HTTPS
* Automatic compression
* Custom domain support

## Image Processing

For images, you can request transformations:

```
"Generate thumbnails for uploaded images."
```

```
"Resize profile pictures to 200x200."
```

## Multi-Tenant Storage

In multi-tenant mode, files are isolated by organization:

```
files/
├── org-123/
│   ├── tasks/
│   └── users/
├── org-456/
│   ├── tasks/
│   └── users/
```

A user from Org-123 cannot access files from Org-456.

## Security

<AccordionGroup>
  <Accordion title="Signed URLs">
    All uploads and downloads use time-limited signed URLs. Direct bucket access is blocked.
  </Accordion>

  <Accordion title="Encryption">
    Files are encrypted at rest using AES-256 server-side encryption.
  </Accordion>

  <Accordion title="Virus Scanning">
    Optional: Scan uploads for malware before accepting.
  </Accordion>

  <Accordion title="Access Control">
    File access follows the same authorization rules as your entities.
  </Accordion>
</AccordionGroup>

## Example: Document Management

```
"A document management system where:
- Documents belong to folders
- Users can upload files (PDFs, Word, Excel) up to 50MB
- Documents have version history
- Deleted documents are retained for 30 days before permanent deletion"
```

This generates:

* S3 bucket with versioning enabled
* 30-day lifecycle policy for deleted objects
* Signed URLs for secure upload/download
* Content-type validation

<Card title="Lovable Integration" icon="heart" href="/integrations/lovable">
  Learn how to build frontends with file uploads in Lovable.
</Card>