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

# URL structure

> How CDN endpoints, custom domains, file IDs, and CDN slugs compose your public image URLs.

Convertly CDN URLs have three independent layers you can customize. Each layer solves a different problem — hostname branding, workspace routing, and file identity. Library assets use [Convertly HDAM](/docs/image-cdn/hdam-storage) identifiers (UUID or slug); origin assets use `/o/{originSlug}/…` paths.

```
https://{hostname}/{endpointNamespace}/{fileIdOrSlug}?w=1200&format=auto
```

| Layer               | Default                    | Optional upgrade                                                                                               | What it controls                                                     |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Hostname**        | `cdn.convertly.sh`         | [Custom domain](/docs/image-cdn/custom-domain) (`cdn.yourdomain.com`)                                          | Branding in browser devtools, emails, and social previews            |
| **CDN endpoint**    | Workspace default endpoint | Additional endpoint with a URL namespace (`marketing`, `site`, `products`)                                     | Which workspace owns the URL and whether signed delivery is required |
| **File identifier** | Stored file UUID           | Generated/editable [CDN slug](#cdn-slugs) (`hero-summer`, `catalog-card-01`) or [origin path](#origin-sources) | Which asset the URL resolves to                                      |

All three compose. A production marketing site often ends up with:

```
https://cdn.acme.com/marketing/hero-summer?w=1200&format=auto&q=auto
```

Same transforms, same edge cache, your hostname, a readable endpoint path, and a slug instead of a UUID.

## Storage files: UUID fallback

When you upload to [Convertly Storage](/docs/files-and-storage), every file gets an immutable internal id (UUID). That UUID URL is always available:

```
https://cdn.convertly.sh/assets-acme/7c3f2a91-8b64-4d5e-a2f7-91c06b48de35?w=800
```

UUID fallback is deliberate:

* **Stable caching** — the URL never changes when you rename the display filename in the file manager.
* **Not enumerable** — scrapers cannot guess other files in your workspace.
* **Immutable asset pattern** — upload a new version as a new file id when you want a fresh cache (see [Replacing a file](/docs/image-cdn/operations#replacing-a-file)).

Renaming a file in the dashboard (`PATCH /api/files/{id}` with `filename`) updates the label in Convertly Storage only. It does **not** change existing CDN URLs or regenerate the slug.

## CDN slugs

Stored files receive a readable **CDN slug** from the filename when they are created. For example, `hero summer.jpg` becomes `hero-summer`. If another file already uses that slug in the workspace, Convertly appends a short suffix such as `hero-summer-2`.

You can edit or remove the slug from the file action menu. Removing the slug makes copied CDN URLs use the file UUID, but existing UUID URLs always keep working.

```bash theme={"system"}
curl -X PATCH "https://convertly.sh/api/files/{fileId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cdnSlug": "hero-summer" }'
```

Then embed:

```
https://cdn.convertly.sh/marketing/hero-summer?w=1200&format=auto
```

(with `marketing` as the endpoint's URL namespace)

### Slug rules

* 3–80 characters
* Lowercase letters, digits, hyphens, underscores
* Must start with a letter or digit
* Unique per workspace (409 if already taken)
* Reserved names (`api`, `cdn`, `v1`, …) are blocked
* Set `cdnSlug: null` to remove a slug and fall back to the UUID URL

### UUID URLs still work

When a slug is set, **both** URLs resolve to the same file:

```
https://cdn.convertly.sh/marketing/hero-summer?w=800
https://cdn.convertly.sh/marketing/7c3f2a91-8b64-4d5e-a2f7-91c06b48de35?w=800
```

Prefer the slug in new markup. Keep the UUID URL working for existing embeds.

### Slugs vs folders

[Folders](/docs/files-and-storage) organize files in the Convertly file manager. They do **not** appear in library CDN URLs. That separation is part of [Convertly HDAM](/docs/image-cdn/hdam-storage).

| Feature          | In file manager         | In CDN URL                             |
| ---------------- | ----------------------- | -------------------------------------- |
| Folder tree      | Yes                     | No (not yet)                           |
| Display filename | Yes                     | No — use slug or UUID                  |
| CDN slug         | Yes (flat, one segment) | Yes — `{slug}` only, not `folder/slug` |

If you need multi-segment URLs like `catalog/products/hero.jpg` without uploading to Convertly Storage, use an [origin source](/docs/image-cdn/url-structure#origin-sources) pointed at a public HTTPS bucket or site.

## Origin sources

For assets on a public HTTPS origin (deployed site, public bucket, existing CDN) or a **private** bucket connected as an origin source:

```
https://cdn.convertly.sh/{endpointNamespace}/o/{originSlug}/products/hero.jpg?w=1200
```

You control the full path after `/o/{originSlug}/`. This is the right choice when:

* Images live in your repo's `public/` folder on a deployed site
* You already publish assets to a bucket with folder structure
* You want SEO-friendly paths without uploading to Convertly Storage
* Assets live in a **private** object bucket (connect with encrypted credentials in **Image CDN → Sources**)

## Video poster URLs

Video files uploaded to Convertly Storage can serve poster images through the same delivery URL shape as images:

```
https://cdn.convertly.sh/{endpointNamespace}/{videoFileId}?t=2&w=640&format=webp
```

## Video clip URLs

Trim, resize, and transcode stored videos from the CDN using the same endpoint and file ID:

```
https://cdn.convertly.sh/{endpointNamespace}/{videoFileId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{endpointNamespace}/{videoFileId}?format=gif&so=1&du=3&w=480
```

See [Video transforms](/docs/image-cdn/transforms/video) for all parameters. Without transform params, video URLs redirect to a signed download. For adaptive HLS/DASH playback from stored sources, see [Video streaming](/docs/video-streaming).

## CDN endpoints

CDN endpoints replace long, rotatable credentials in URLs. The endpoint owns a stable URL namespace and an access policy:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/cdn-delivery-sources" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing site", "namespace": "marketing", "mode": "public" }'
```

Check availability before creating:

```bash theme={"system"}
curl "https://convertly.sh/api/delivery-keys/alias?alias=marketing" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
```

The `alias` query parameter name is kept for backward compatibility; it checks URL namespace availability. URL namespaces are set when an endpoint is created, are globally unique, and are safe to embed in HTML alongside custom domains. Per-plan endpoint limits are in [Limits](/limits). See [Operations](/docs/image-cdn/operations) for access policies, URL signing keys, and purge.

## Custom domains

On Starter and above, bind `cdn.yourdomain.com` (or similar) to your workspace. The path structure is identical — only the hostname changes.

Set the hostname in your SDK config:

```ts theme={"system"}
createConvertlyCdn({
  namespace: process.env.NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE!,
  baseUrl: "https://cdn.yourdomain.com",
});
```

There is no separate dashboard toggle for this — pass `baseUrl` (or `NEXT_PUBLIC_CONVERTLY_CDN_HOST`) in your app environment. See [Custom domain](/docs/image-cdn/custom-domain).

## Choosing an approach

<Columns cols={2}>
  <Card title="Convertly Storage + UUID" icon="database">
    Simplest default. Upload, copy file id, embed. Best when URLs stay internal or you rotate ids on updates.
  </Card>

  <Card title="Storage + CDN slug" icon="tag">
    Same as above but readable paths when you opt in. Good for marketing assets with stable public names.
  </Card>

  <Card title="Origin source" icon="folder">
    Assets stay on your site or bucket. Origin-mapped URLs under `/o/{originSlug}/…`. No Convertly upload required.
  </Card>

  <Card title="Endpoint + custom domain" icon="globe">
    Brand the hostname while keeping the endpoint identity stable. Works with UUID or slug file identifiers.
  </Card>
</Columns>

## Next steps

<Columns cols={2}>
  <Card title="Operations" icon="shield-halved" href="/docs/image-cdn/operations">
    CDN endpoints, URL signing keys, purge, security.
  </Card>

  <Card title="Convertly HDAM" icon="folder-tree" href="/docs/image-cdn/hdam-storage">
    Hybrid library storage, origins, and direct CDN asset mapping.
  </Card>

  <Card title="Custom domain" icon="globe" href="/docs/image-cdn/custom-domain">
    CNAME setup and SSL provisioning.
  </Card>

  <Card title="Plan limits" icon="gauge-high" href="/limits">
    Delivery allowances, custom domain counts, and CDN endpoint limits by plan.
  </Card>
</Columns>