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

# Gallery API

> Manage workspace media: list, upload, localize, organize, and inspect usage.

## Endpoints

| Method | Path                                 | Description                                                     |
| ------ | ------------------------------------ | --------------------------------------------------------------- |
| GET    | `/v1/gallery/files`                  | List gallery files with filtering, pagination, and localization |
| PUT    | `/v1/gallery/files/:id`              | Update file metadata (tags, folder, status)                     |
| PUT    | `/v1/gallery/files/:id/translations` | Upsert localized alt text and descriptions                      |
| DELETE | `/v1/gallery/files/:id`              | Schedule file deletion and enqueue removal                      |
| POST   | `/v1/gallery/upload`                 | Upload a file (multipart or JSON payload)                       |
| POST   | `/v1/gallery/upload/direct`          | Create resumable upload URL for large videos                    |
| GET    | `/v1/gallery/download/:id`           | Download or redirect to provider playback URL                   |
| GET    | `/v1/gallery/folders`                | List folders in the workspace                                   |
| POST   | `/v1/gallery/folders`                | Create a folder                                                 |
| GET    | `/v1/gallery/stats`                  | Retrieve storage and file counts                                |

<Info>
  Scopes: `gallery:read` grants listing, downloads, stats. `gallery:write` allows uploads, metadata updates, folder creation, and translations. `gallery:delete` is required to schedule deletions. All routes resolve workspace context from the API key/session; do not send manual workspace headers.
</Info>

## Key concepts

* Files are stored per workspace. Status reflects the processing state (`completed`, `processing`, `deleting`, etc.).
* Listing resolves localized alt/description metadata using `locale` and `fallbackLocale`. Pass `includeMeta=1` to embed translation maps and supported languages.
* Uploads accept raw multipart files or base64 JSON payloads. The API picks the storage provider automatically based on MIME type and returns a 202 response while background processing finishes. For large videos (>100MB), use the resumable upload endpoint which supports the TUS protocol.
* Deleting a file is asynchronous: the API marks the record as `deleting` and emits `gallery.file.deleted` webhooks once storage cleanup is complete.
* Folder operations are flat: responses return `parentId` and `path` so clients can construct trees client-side.
* Stats aggregate file counts and storage usage to help monitor quotas.