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

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.

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.