The Media API provides a centralized interface for managing all assets within SveltyCMS. It handles multi-part uploads, intelligent deduplication, virtual folder organization (logical folderId moves), and DAM features (analytics, versioning, bulk download, secure sharing).

⚡ Quick Reference

1. Asset Management

Uploading Assets

SveltyCMS supports single and bulk uploads via standard multipart/form-data.

Standard endpoint: POST /api/media (or POST /api/media/upload)
Payload: files field (array or single stream), optional folder field (virtual folder ID or "global").

Streaming endpoint (large payloads): POST /api/media/stream
Payload: Same multipart/form-data shape; parsed via streaming-upload.ts with backpressure-safe chunk handling. The folder field is captured before file parts are processed.

Client-Side Routing (upload-client.ts)

The admin UI does not call these endpoints directly for every upload. uploadMediaFiles() in src/utils/media/upload-client.ts auto-routes:

Used by mediagallery/+page.svelte and upload-media/local-upload.svelte.

Folders & Structure

Virtual folders organize the asset library without relocating physical files on disk or object storage. Each media row stores an optional folderId pointing at a system virtual folder (or null for media root).

Folder context on upload is resolved server-side by MediaService.saveMedia().

Move Media (Virtual Folder)

Endpoint: POST /api/media/move
Permission: media:write
Handler: handleMediaMove in handlers/media.ts
SDK: LocalCMS → media.move(fileIds, targetFolderId, { tenantId })
Adapter: dbAdapter.media.files.move(fileIds, targetFolderId?, tenantId?)

Moves one or many assets into a virtual folder (or back to media root). Does not rewrite storage paths, invalidate share tokens, or reprocess thumbnails.

Payload:

{
  "fileIds": ["uuid-1", "uuid-2"],
  "targetFolderId": "folder-uuid-or-null"
}

Success response:

{
  "success": true,
  "data": {
    "movedCount": 2,
    "fileIds": ["uuid-1", "uuid-2"],
    "targetFolderId": "folder-uuid"
  }
}

Client helper: moveMediaToFolder() in src/utils/media/media-dnd.ts posts this endpoint and dispatches a document-level mediaMoved event so the gallery can refresh optimistically.

Admin UI — drag & drop

The Media Gallery treats the sidebar folder tree and breadcrumb ancestors as equivalent drop targets for the same multi-id payload:

• Custom MIME: application/x-sveltycms-media-ids ({ ids: string[] })
• Shared helpers: beginMediaDrag, resolveMediaDragIds, hasMediaDrag in media-dnd.ts
• Mobile: limited sidebar space — prefer breadcrumb drop, or select items and tap a parent crumb to move

Folder tree CRUD remains on /api/system-virtual-folder (create/rename/reorder/delete folders).

2. Media Processing

Auto-Deduplication

The media engine calculates high-entropy hashes (SHA-256) for every upload. If an identical file already exists in the system, SveltyCMS will automatically link the new metadata to the existing physical file, saving storage space.

Asynchronous Operations

For long-running tasks (AI tagging, batch transforms, heavy ingestion), the API returns a 202 Accepted status with an OperationID.

Endpoint: GET /api/media/jobs/{id}
Returns:

• pending: Job is in queue.
• processing: Job is currently executing.
• completed: Job finished successfully.
• failed: Job encountered an error (includes error details).

Image Manipulation API

SveltyCMS provides a dedicated endpoint for server-side image baking.

Endpoint: POST /api/media/manipulate/{id}
Payload: JSON instructions for transformations.

{
  "rotation": 90,
  "flipH": true,
  "crop": { "x": 10, "y": 10, "width": 500, "height": 500 },
  "filters": { "brightness": 10, "contrast": 5 },
  "focalPoint": { "x": 45, "y": 60 },
  "saveBehavior": "overwrite"
}

Focal Point & Aspect Preview

SveltyCMS supports focal point metadata on images — a percentage coordinate ({ x, y } from 0–100) marking the most important visual area. This is used by frontend rendering (CSS object-position) or server-side cropping tools to ensure the subject remains visible regardless of container aspect ratio.

Update focal point (lightweight, metadata-only):

PATCH /api/media/{id}
Content-Type: application/json

{ "metadata": { "focalPoint": { "x": 35, "y": 60 } } }

Aspect Ratio Preview — A companion UI (available via the Focal Point plugin) shows how an image crops to 16:9, 1:1, 4:3, and other ratios with the focal point as the visual anchor. See the Focal Point Plugin documentation.

Data model: CmsMediaMetadata.focalPoint?: { x: number; y: number } — stored in media_files.metadata, returned in all media GET responses.

3. The Mechanics

Storage Adapters

The Media API is storage-agnostic. It can be configured to use local disk storage, AWS S3, or Cloudflare R2 through the MediaAdapter interface.

4. DAM — Digital Asset Management

Bulk Download

Download multiple media files as a single TAR.GZ archive.

Endpoint: GET /api/media/bulk-download?id={id1}&id={id2}&…
Returns: application/gzip binary stream with Content-Disposition: attachment.

Admin UI: When one or more assets are selected in the Media Gallery, the selection toolbar exposes a Download Archive button that builds the query string from selectedFiles and triggers a browser download.

Storage Analytics

Retrieve storage breakdowns, insights, and growth trends.

Endpoint: GET /api/media/analytics
Returns: JSON wrapped in { success: true, data: { … } } with:

• total — file count, byte size, formattedSize
• byType — top 5 types by storage share
• insights — actionable cards (large files, old files, dominant types)
• trends — last 12 months of upload growth
• quota — used/available bytes, percentage, healthy | warning | critical status

Admin UI: Dashboard widget media-storage-analytics-widget.svelte polls this endpoint every 60 seconds. Add it from the dashboard widget picker.

Version History

Track, compare, and restore file versions over time.

Admin UI: The Versions tab in media-details-modal.svelte provides upload, restore, per-version download, and a Compare Versions panel (From/To selects + diff results) when ≥2 historical versions exist.

Compare response shape:

{
  "success": true,
  "data": {
    "fromVersion": 1,
    "toVersion": 2,
    "contentChanged": true,
    "metadataChanged": false,
    "sizeDifference": 4096,
    "changes": [{ "field": "content", "type": "modify", "oldValue": "…", "newValue": "…" }]
  }
}

Secure Share Links

Generate expiring, password-protected share links for media assets. See also Media Sharing Endpoint.

Admin UI: The Share tab in media-details-modal.svelte generates links with configurable expiry and optional password, lists active tokens, and supports one-click revocation.

Related Documents

• Media System Architecture — virtual folders, gallery DnD, integrity gate
• Media Sharing Endpoint — share links (unaffected by virtual folder moves)
• Collections Reference (collections.ts)
• System Reference (system.ts) — system-virtual-folder namespace