> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Convertly HDAM

> Hybrid Digital Asset Management: managed library storage, external origins, metadata, and stable CDN delivery in one workspace.

**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.

<Info>
  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.
</Info>

## Two layers, one platform

```mermaid actions={false} theme={"system"}
flowchart LR
  subgraph workspace ["Workspace (private)"]
    folders["Folder tree"]
    files["Files with display names"]
    meta["Tags, descriptions, AI metadata"]
  end

  subgraph delivery ["CDN (public)"]
    ns["CDN endpoint"]
    id["File UUID or CDN slug"]
    transforms["Transform params"]
  end

  folders --> files
  files -->|"stable mapping"| id
  ns --> id
  id --> transforms
```

| Layer         | What it is                                                        | Changes when you reorganize?                                               |
| ------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Workspace** | Folders, filenames, tags, parent/child relationships              | Yes. That is the point.                                                    |
| **Delivery**  | `https://cdn.convertly.sh/{endpointNamespace}/{fileIdOrSlug}?w=…` | No. The endpoint resolves the URL to 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 CDN                           | HDAM library                                           |
| ------------------------------------------- | ------------------------------------------------------ |
| Moving a file changes the public URL        | Move freely inside the workspace                       |
| Renaming a folder invalidates nested URLs   | Folder names are workspace-only                        |
| Long paths for deep origin trees            | One endpoint segment + one file identifier             |
| Hard for AI/tools to reorganize safely      | Agents can move, tag, and sort without breaking embeds |
| Folder structure must match production URLs | Folder structure matches how *you* work                |

For assets that should stay on an external origin, use [origin sources](/docs/image-cdn/url-structure#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:

```
GET /cdn/v1/{endpointNamespace}/{fileIdOrSlug}?w=1200&format=auto
```

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

| Identifier   | Example segment                        | When to use                                                                                                |
| ------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **UUID**     | `7c3f2a91-8b64-4d5e-a2f7-91c06b48de35` | Default. Immutable, non-guessable, never tied to folder layout.                                            |
| **CDN slug** | `hero-summer`                          | Readable 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](/docs/image-cdn/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 ─┘ └ endpoint ┘ └─ 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 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](/docs/image-cdn/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:

```
https://cdn.convertly.sh/{endpointNamespace}/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](/docs/image-cdn#storage-or-origin-sources) and [Operations → Origin sources](/docs/image-cdn/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

<Columns cols={2}>
  <Card title="URL structure" icon="link" href="/docs/image-cdn/url-structure">
    CDN endpoints, slugs, UUIDs, and origin path composition.
  </Card>

  <Card title="Files and storage" icon="database" href="/docs/files-and-storage">
    Folders, uploads, and how storage relates to the CDN.
  </Card>

  <Card title="Plan limits" icon="gauge-high" href="/limits">
    HDAM storage allowances and file size limits by plan.
  </Card>
</Columns>