Skip to main content

​
Endpoints

MethodPathDescription
GET/v1/gallery/filesList gallery files with filtering, pagination, and localization
PUT/v1/gallery/files/:idUpdate file metadata (tags, folder, status)
PUT/v1/gallery/files/:id/translationsUpsert localized alt text and descriptions
DELETE/v1/gallery/files/:idSchedule file deletion and enqueue removal
POST/v1/gallery/uploadUpload a file (multipart or JSON payload)
GET/v1/gallery/download/:idDownload or redirect to provider playback URL
GET/v1/gallery/foldersList folders in the workspace
POST/v1/gallery/foldersCreate a folder
GET/v1/gallery/statsRetrieve 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 with metadata derived from the upload provider (Cloudflare R2, Images, or Stream). 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.
  • Deleting a file is asynchronous: the API marks the record as deleting, enqueues work on gallery-operations-queue, 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.