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

# Overview

> Upload, retrieve, and manage files and images in Sublay

## Overview

Sublay's storage system lets you upload files and images on behalf of authenticated users. Uploaded assets are stored in managed cloud storage and served through a proxy URL so direct storage credentials are never exposed to the client.

<Note>
  **Requires the `files-images` bundle.** File and image uploads are only available when the `files-images` bundle is installed on your project. See [Bundles](/v8/bundles) to add it.
</Note>

Files can be optionally associated with an entity, comment, or space, enabling cascade deletion when the parent object is removed.

## Upload Modes

Sublay provides two hooks for uploading assets:

* **Image upload** — server-side processing with automatic variant generation (resizing, format conversion, EXIF stripping). Returns named variants for responsive display.
* **File upload** — generic upload for documents, videos, and other files. No server-side processing — the file is stored as-is and a proxy URL is returned.

## Image Processing Modes

When uploading images, you choose a **processing mode** that defines how variants are generated:

| Mode | Description |
| - | - |
| `exact-dimensions` | Each variant has an explicit `{ width, height }`. Use for fixed-size crops. |
| `aspect-ratio-width-based` | All variants share an aspect ratio; you specify widths. Heights are computed. |
| `aspect-ratio-height-based` | All variants share an aspect ratio; you specify heights. Widths are computed. |
| `original-aspect` | Preserves the source aspect ratio; you specify the longest-edge size for each variant. |
| `multi-aspect-ratio` | Multiple aspect ratios combined with explicit sizes. |

## File Size Limits

| Upload type | Limit |
| - | - |
| Image upload | 50 MB |
| Generic file upload | 50 MB |

## Hooks

<CardGroup cols={2}>
  <Card title="useUploadImage" href="/v8/hooks/storage/use-upload-image">
    Upload and process an image with automatic variant generation.
  </Card>

  <Card title="useUploadFile" href="/v8/hooks/storage/use-upload-file">
    Upload a generic file and receive a proxy URL.
  </Card>
</CardGroup>

## API Reference

* [Upload Image](/v8/api-reference/storage/upload-image) — `POST /v8/:projectId/storage/images`
* [Upload File](/v8/api-reference/storage/upload-file) — `POST /v8/:projectId/storage`
* [Fetch File](/v8/api-reference/storage/fetch-file) — `GET /v8/:projectId/storage/:fileId`
* [Delete File](/v8/api-reference/storage/delete-file) — `DELETE /v8/:projectId/storage/:fileId`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.