---
title: Storage SDK Reference
description: File upload, download, and management with the InsForge SDK
---

import Installation from '/snippets/sdk-installation.mdx';

<Installation />

## from()

Get a bucket instance for file operations.

### Parameters

- `bucketName` (string, required) - Name of the storage bucket

### Returns

```typescript
StorageBucket // Instance with upload, uploadAuto, download, remove methods
```

### Example

```javascript
const bucket = insforge.storage.from('avatars')
```

---

## upload()

Upload a file with a specific path/key.

### Parameters

- `path` (string, required) - The object key/path for the file
- `file` (File | Blob, required) - File or Blob to upload

### Returns

```typescript
{
  data: {
    bucket: string,
    key: string,
    size: number,
    mimeType: string,
    uploadedAt: string,
    url: string
  } | null,
  error: Error | null
}
```

<Warning>
If a file with the same key exists, backend auto-renames it. Always use the returned `key` and `url`.
</Warning>

### Example

```javascript
const { data, error } = await insforge.storage
  .from('avatars')
  .upload('user-123/avatar.jpg', fileObject)

// Save BOTH url and key to database
await insforge.database
  .from('users')
  .update({
    avatar_url: data.url,
    avatar_key: data.key  // Save key for download/delete operations
  })
  .eq('id', 'user-123')
```

### Output

```json
{
  "data": {
    "bucket": "avatars",
    "key": "user-123/avatar.jpg",
    "size": 45678,
    "mimeType": "image/jpeg",
    "uploadedAt": "2024-01-15T10:30:00Z",
    "url": "https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user-123%2Favatar.jpg"
  },
  "error": null
}
```

---

## uploadAuto()

Upload a file with auto-generated unique key.

### Parameters

- `file` (File | Blob, required) - File or Blob to upload

### Returns

```typescript
{
  data: {
    bucket: string,
    key: string,
    size: number,
    mimeType: string,
    uploadedAt: string,
    url: string
  } | null,
  error: Error | null
}
```

### Example

```javascript
const { data, error } = await insforge.storage
  .from('uploads')
  .uploadAuto(fileObject)

// Save url and key to database
await insforge.database
  .from('posts')
  .insert([{
    image_url: data.url,
    image_key: data.key,  // Save key for download/delete operations
    user_id: userId
  }])
```

### Output

```json
{
  "data": {
    "bucket": "uploads",
    "key": "myfile-1705315200000-abc123.jpg",
    "size": 45678,
    "mimeType": "image/jpeg",
    "uploadedAt": "2024-01-15T10:30:00Z",
    "url": "https://your-app.region.insforge.app/api/storage/buckets/uploads/objects/myfile-1705315200000-abc123.jpg"
  },
  "error": null
}
```

---

## download()

Download a file as Blob.

### Parameters

- `path` (string, required) - The object key/path to download

### Returns

```typescript
{
  data: Blob | null,
  error: Error | null
}
```

### Example

```javascript
// 1. Get the file key from your database
const { data: user, error: dbError } = await insforge.database
  .from('users')
  .select('avatar_key')
  .eq('id', 'user-123')
  .single()

// 2. Download the file using the key
const { data: blob, error } = await insforge.storage
  .from('avatars')
  .download(user.avatar_key)

// 3. Create download link or display image
const url = URL.createObjectURL(blob)
const img = document.querySelector('img')
img.src = url
```

### Output

```json
{
  "data": "Blob { size: 45678, type: 'image/jpeg' }",
  "error": null
}
```

---

## remove()

Delete a file from storage.

### Parameters

- `path` (string, required) - The object key/path to delete

### Returns

```typescript
{
  data: { message: string } | null,
  error: Error | null
}
```

### Example

```javascript
// 1. Get the file key from your database
const { data: user, error: dbError } = await insforge.database
  .from('users')
  .select('avatar_key')
  .eq('id', 'user-123')
  .single()

// 2. Delete the file from storage
const { data, error } = await insforge.storage
  .from('avatars')
  .remove(user.avatar_key)

// 3. Clear the database reference
await insforge.database
  .from('users')
  .update({ avatar_url: null, avatar_key: null })
  .eq('id', 'user-123')
```

### Output

```json
{
  "data": {
    "message": "Object deleted successfully"
  },
  "error": null
}
```