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.
The object you create and manage is a CDN endpoint. Each endpoint has a short URL namespace, which is only the public path segment after cdn.convertly.sh. The namespace is not a credential or a separate resource.

​
Two layers, one platform

When you move hero-summer.jpg from Campaigns / Q1 to Approved / Homepage, only folder_id in metadata updates. The CDN URL
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:
The URL encodes the origin path. That creates problems for managed library assets that you reorganize inside Convertly: 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 CDN endpoint:
  1. Resolve {endpointNamespace} to an active CDN endpoint and its workspace.
  2. Match fileIdOrSlug against the workspace’s file IDs and CDN slugs.
  3. Fetch the matching original from Convertly Storage without exposing its storage location in the URL.
  4. Apply transforms, cache globally, respond.
Folders and display filenames are not part of this lookup.

​
Identifiers you can embed

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:
Compare to mirroring a deep origin tree in the URL:
The endpoint routes traffic to your workspace and enforces its access policy. The file segment identifies the asset. Transform parameters describe the variant. Nothing else is required in the path. With a custom domain mapped to one endpoint, the endpoint path segment can drop from the URL 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:
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.
  • CDN endpoint determines which workspace or site context owns the URL namespace and whether URLs must be signed.
  • 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

CDN endpoints, 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.
Last modified on July 31, 2026