Skip to main content
HDAM (Hybrid Digital Asset Management) combines a managed asset library with external origin sources, metadata for any file type, and CDN URLs that map directly to each asset by id or slug rather than folder path. Most origin-backed CDNs mirror the origin folder tree in the URL. That works until someone renames a folder, moves assets for a campaign, or an AI agent tidies the library. Every embed breaks, cache keys change, and you chase broken links. HDAM keeps workspace organization and public delivery separate.

​
Two layers, one platform

LayerWhat it isChanges when you reorganize?
WorkspaceFolders, filenames, tags, parent/child relationshipsYes. That is the point.
Deliveryhttps://cdn.convertly.sh/{namespace}/{fileIdOrSlug}?w=…No. The URL points at the file record, not its folder path.
When you move hero-summer.jpg from Campaigns / Q1 to Approved / Homepage, only folder_id in metadata updates. The CDN URL 
https://cdn.convertly.sh/marketing/hero-summer?w=1200&format=auto
keeps working. Edge cache entries keyed on that URL stay valid.

​
Library URLs vs origin URLs

Origin-mapped delivery looks familiar when assets stay on a deployed site or bucket: 
https://cdn.example.com/marketing/campaigns/q1/hero-summer.jpg?w=1200
The URL encodes the origin path. That creates problems for managed library assets that you reorganize inside Convertly:
Origin-mapped CDNHDAM library
Moving a file changes the public URLMove freely inside the workspace
Renaming a folder invalidates nested URLsFolder names are workspace-only
Long paths for deep origin treesOne namespace segment + one file identifier
Hard for AI/tools to reorganize safelyAgents can move, tag, and sort without breaking embeds
Folder structure must match production URLsFolder structure matches how you work
For assets that should stay on an external origin, use origin sources. Convertly fetches from your site, bucket, or CDN and serves transforms at /o/{originSlug}/….

​
How a CDN request resolves

For Convertly Storage, the delivery route loads a file by UUID or CDN slug, scoped to the workspace that owns the delivery namespace: 
GET /cdn/v1/{namespace}/{fileIdOrSlug}?w=1200&format=auto
  1. Resolve {namespace} to the workspace delivery source.
  2. Look up stored_files where id = fileIdOrSlug or cdn_slug = fileIdOrSlug.
  3. Fetch the file from Convertly Storage using the internal storage_path (never exposed in the URL).
  4. Apply transforms, cache globally, respond.
Folders, display filenames, and internal storage paths are not part of this lookup.

​
Identifiers you can embed

IdentifierExample segmentWhen to use
UUID11111111-1111-1111-1111-111111111111Default. Immutable, non-guessable, never tied to folder layout.
CDN slughero-summerReadable public alias. Generated from filename on upload and stable until you explicitly edit or clear it.
Both resolve to the same file. Prefer slugs in new markup; keep UUID URLs for existing integrations. Renaming the display filename in the file manager does not change CDN URLs. Moving a file only updates folder_id; the UUID and current slug stay attached to the same file record. Editing or clearing a slug is explicit (PATCH /api/files/{id} with cdnSlug). See URL structure.

​
Workspace operations that stay safe

These update workspace metadata only. They do not invalidate CDN URLs for library assets:
  • Move a file between folders (folder_id)
  • Rename a folder
  • Reorder or nest folders
  • Rename the display filename
  • Add tags, descriptions, or AI-generated metadata
Operations that do change delivery (by design):
  • Delete the file
  • Change or remove a CDN slug (existing slug URLs stop resolving; UUID URLs still work because the file id is unchanged)
  • Upload a replacement as a new file id when you want a fresh cache generation
Forma AI, MCP agents, and dashboard automations can reorganize libraries because delivery identity is decoupled from folder hierarchy.

​
Short URLs by design

A typical library CDN URL has three readable parts plus transforms: 
https://cdn.convertly.sh/marketing/hero-summer?w=1200&format=auto
         └─ hostname ─┘ └─ ns ─┘ └─ slug ─┘
Compare to mirroring a deep origin tree in the URL: 
https://cdn.convertly.sh/marketing/client-acme/campaigns/2026/q1/social/hero-summer.jpg?w=1200
The namespace routes traffic to your workspace. The file segment identifies the asset. Transform params describe the variant. Nothing else is required in the path. With a custom domain mapped to one delivery source, the namespace segment can drop from the path entirely while direct asset mapping stays the same.

​
When to use origin sources

Origin sources fit when:
  • Assets already live on a deployed public/ folder or static host
  • You publish from an object bucket with a fixed key layout
  • You need multi-segment paths like catalog/products/shoe-01.jpg without uploading to Convertly Storage
  • A private bucket should stay private while Convertly fetches with stored credentials
Origin URL shape: 
https://cdn.convertly.sh/{namespace}/o/{originSlug}/catalog/products/hero.jpg?w=1200
You can run both in one workspace: HDAM library assets with direct id/slug URLs, and origin delivery for assets that stay on external hosts. See Storage or origin sources and Operations → Origin sources.

​
Mental model

Hybrid asset management with a stable public address for each library file:
  • Folders are how you and your team (or agents) find and govern files inside Convertly.
  • File id / slug is the public identity the internet uses. File ids are immutable; slugs are stable editable aliases.
  • Namespace is which workspace or site context owns that name.
  • Origin sources serve assets that remain on your site, bucket, or external CDN.
That split is what lets Convertly behave like a full asset library while still supporting origin delivery when you need it.

​
Next steps

URL structure

Namespaces, slugs, UUIDs, and origin path composition.

Files and storage

Folders, uploads, and how storage relates to the CDN.

Plan limits

HDAM storage allowances and file size limits by plan.