URL structure

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 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 (`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 (`hero-summer`, `catalog-card-01`) or origin path	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, 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).

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.

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 organize files in the Convertly file manager. They do not appear in library CDN URLs. That separation is part of Convertly HDAM.

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 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 for all parameters. Without transform params, video URLs redirect to a signed download. For adaptive HLS/DASH playback from stored sources, see Video streaming.

CDN endpoints

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

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:

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. See 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:

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.

Choosing an approach

Convertly Storage + UUID

Simplest default. Upload, copy file id, embed. Best when URLs stay internal or you rotate ids on updates.

Storage + CDN slug

Same as above but readable paths when you opt in. Good for marketing assets with stable public names.

Origin source

Assets stay on your site or bucket. Origin-mapped URLs under /o/{originSlug}/…. No Convertly upload required.

Endpoint + custom domain

Brand the hostname while keeping the endpoint identity stable. Works with UUID or slug file identifiers.

Next steps

Operations

CDN endpoints, URL signing keys, purge, security.

Convertly HDAM

Hybrid library storage, origins, and direct CDN asset mapping.

Custom domain

CNAME setup and SSL provisioning.

Plan limits

Delivery allowances, custom domain counts, and CDN endpoint limits by plan.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Storage files: UUID fallback

CDN slugs

Slug rules

UUID URLs still work

Slugs vs folders

Origin sources

Video poster URLs

Video clip URLs

CDN endpoints

Custom domains

Choosing an approach

Convertly Storage + UUID

Storage + CDN slug

Origin source

Endpoint + custom domain

Next steps

Operations

Convertly HDAM

Custom domain

Plan limits

​Storage files: UUID fallback

​CDN slugs

​Slug rules

​UUID URLs still work

​Slugs vs folders

​Origin sources

​Video poster URLs

​Video clip URLs

​CDN endpoints

​Custom domains

​Choosing an approach

Convertly Storage + UUID

Storage + CDN slug

Origin source

Endpoint + custom domain

​Next steps

Operations

Convertly HDAM

Custom domain

Plan limits

Storage files: UUID fallback

CDN slugs

Slug rules

UUID URLs still work

Slugs vs folders

Origin sources

Video poster URLs

Video clip URLs

CDN endpoints

Custom domains

Choosing an approach

Next steps