---
title: Storage
description: Storage protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Storage Service Protocol

Defines the API contract for client-side file operations.

Focuses on secure, direct-to-cloud uploads (Presigned URLs)

rather than proxying bytes through the API server.

<Callout type="info">
**Source:** `packages/spec/src/api/storage.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } from '@objectstack/spec/api';
import type { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } from '@objectstack/spec/api';

// Validate data
const result = CompleteChunkedUploadRequest.parse(data);
```

---

## CompleteChunkedUploadRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **uploadId** | `string` | ✅ | Multipart upload session ID |
| **parts** | `Object[]` | ✅ | Ordered list of uploaded parts for assembly |


---

## CompleteChunkedUploadResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## CompleteUploadRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **fileId** | `string` | ✅ | File ID returned from presigned request |
| **eTag** | `string` | optional | S3 ETag verification |


---

## FileTypeValidation

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **mode** | `Enum<'whitelist' \| 'blacklist'>` | ✅ | whitelist = only allow listed types, blacklist = block listed types |
| **mimeTypes** | `string[]` | ✅ | List of MIME types to allow or block (e.g., "image/jpeg", "application/pdf") |
| **extensions** | `string[]` | optional | List of file extensions to allow or block (e.g., ".jpg", ".pdf") |
| **maxFileSize** | `integer` | optional | Maximum file size in bytes |
| **minFileSize** | `integer` | optional | Minimum file size in bytes (e.g., reject empty files) |


---

## FileUploadResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ | Uploaded file metadata |


---

## GetPresignedUrlRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **filename** | `string` | ✅ | Original filename |
| **mimeType** | `string` | ✅ | File MIME type |
| **size** | `number` | ✅ | File size in bytes |
| **scope** | `string` | ✅ | Target storage scope (e.g. user, private, public) |
| **bucket** | `string` | optional | Specific bucket override (admin only) |


---

## InitiateChunkedUploadRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **filename** | `string` | ✅ | Original filename |
| **mimeType** | `string` | ✅ | File MIME type |
| **totalSize** | `integer` | ✅ | Total file size in bytes |
| **chunkSize** | `integer` | ✅ | Size of each chunk in bytes (minimum 5MB per S3 spec) |
| **scope** | `string` | ✅ | Target storage scope |
| **bucket** | `string` | optional | Specific bucket override (admin only) |
| **metadata** | `Record<string, string>` | optional | Custom metadata key-value pairs |


---

## InitiateChunkedUploadResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## PresignedUrlResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## UploadChunkRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **uploadId** | `string` | ✅ | Multipart upload session ID |
| **chunkIndex** | `integer` | ✅ | Zero-based chunk index |
| **resumeToken** | `string` | ✅ | Resume token from initiate response |


---

## UploadChunkResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## UploadProgress

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

