Custom domains

Custom domains replace cdn.convertly.sh with a hostname you control:

https://images.example.com/{fileIdOrSlug}?w=1200&format=auto

The custom hostname maps to one CDN endpoint in your Convertly workspace. The endpoint namespace is omitted from custom-domain URLs, while the equivalent cdn.convertly.sh URL keeps it:

https://cdn.convertly.sh/production/{fileIdOrSlug}?w=1200&format=auto
https://images.example.com/{fileIdOrSlug}?w=1200&format=auto

Both URLs remain valid. Moving files between folders does not change either URL because delivery uses the file UUID or CDN slug. Custom domains are available on Starter and higher plans. See Limits for the number included with each plan.

Before you start

Use a dedicated hostname such as images.example.com, cdn.example.com, or media.example.com.
Do not reuse a hostname that already serves your website or application.
You must be a workspace owner or admin to add, change, or remove a domain.
Confirm the dashboard’s current default CDN endpoint is the one the hostname should represent. A newly added hostname attaches to that endpoint.

Add a domain

Open Images > Domains in the dashboard, or go directly to:

https://convertly.sh/app/image-cdn?tab=domains

Select Add domain and enter the complete hostname without a protocol or path. Convertly attaches the hostname to the workspace’s current default CDN endpoint. If it should serve a different endpoint, set that endpoint as the default before adding the hostname. One hostname maps to one endpoint. Convertly immediately registers the hostname with its managed CDN provider and generates two DNS records:

Type	Name	Value	Purpose
`CNAME`	Your complete hostname	`cdn.convertly.sh`	Routes the hostname to Convertly’s CDN edge
`TXT`	`_convertly-verify.` followed by your hostname	A unique `convertly-domain-verify=` token	Proves control of the hostname

Use the exact names and values shown in the dashboard. Keep the CNAME in DNS only mode if your DNS provider offers an additional proxy option.

Do not copy the example hostname or verification token from this page. Every domain receives a unique TXT value.

Automatic Cloudflare setup

If the domain uses Cloudflare DNS, select Set up with Cloudflare. Convertly uses the Domain Connect synchronous authorization flow, which asks you to approve only the CNAME and TXT records shown on the authorization page. The flow does not grant Convertly ongoing access to your Cloudflare account. After approval, the popup returns a completion signal to the existing Convertly page and Convertly checks the DNS records immediately. Normal background checks continue while DNS propagates. If automatic setup is unavailable for the domain, add the two records manually. Manual and Domain Connect setup produce the same DNS configuration.

Automatic verification

The Domains page checks incomplete domains when the page opens, every 15 seconds while it remains visible, immediately after Domain Connect completes, and again when you return to the browser tab. There is no manual refresh step. The setup moves through these states:

State	Meaning
Checking	Convertly is looking for the required CNAME and TXT records
SSL pending	Ownership and routing are verified; the managed certificate is still being issued or deployed
Verified	DNS, hostname activation, and the managed certificate are ready
Failed	The CDN provider rejected or could not validate the hostname

Convertly treats the domain as ready only after the CNAME and TXT records are detected, the CDN hostname is active, and its SSL status is active. Hostname activation and certificate deployment are separate checks, so SSL pending can briefly remain after DNS is correct.

DNS may appear at different times from different resolvers. Keep the page open or return later; verification resumes automatically.

Use the domain

After verification, the domain card shows the production delivery pattern and a Copy URL action:

https://images.example.com/{slug}

Choose Set as default when new URLs copied for that CDN endpoint should use the custom hostname. Setting a default does not invalidate existing cdn.convertly.sh links or links from another verified hostname. With the JavaScript Image CDN SDK:

import { createConvertlyCdn } from "@convertly-sh/image";

const imageCdn = createConvertlyCdn({
  namespace: process.env.NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE!,
  baseUrl: "https://images.example.com",
});

const url = imageCdn.url("hero-summer", {
  width: 1200,
  format: "auto",
});

The namespace still identifies the endpoint in your SDK configuration, but it is not inserted into a custom-domain URL path.

Public and signed endpoints

A custom domain keeps the access policy of its mapped CDN endpoint:

Endpoint policy	Custom-domain behavior
Public	Anyone with the URL can request the asset
Signed	Requests require a valid signature and expiry

Attaching a custom domain does not make a public endpoint private. Use a signed endpoint for customer-private media and generate signatures only from a trusted backend. See Presets and signing.

Changing or removing a domain

To move traffic to a new hostname:

Add and verify the new hostname.
Set it as the default for the CDN endpoint.
Update your application configuration.
Keep the old hostname connected for as long as previously published URLs must work.

When removing a domain, Convertly first removes the managed custom hostname from its CDN provider. The database record is removed only if provider cleanup succeeds, which avoids leaving an orphaned billable hostname. Remove the customer DNS records after the domain disappears from Convertly.

Troubleshooting

Symptom	Check
CNAME stays undetected	Confirm the complete hostname resolves directly to `cdn.convertly.sh` and any DNS proxy is disabled
TXT stays undetected	Confirm the record name begins with `_convertly-verify.` and the value includes the complete `convertly-domain-verify=` prefix
SSL pending	Leave the CNAME in place. Certificate issuance starts after routing is visible and may finish after ownership verification
Domain returns an origin or routing error	Confirm the domain card is Verified and the CNAME still points to Convertly
Domain entered a failed state	Check for restrictive CAA records, a conflicting hostname at another provider, or contact Convertly support
Domain Connect button is unavailable	Add the displayed records manually; the DNS provider may not expose or onboard the Convertly Domain Connect template

You can inspect public DNS from a terminal:

dig CNAME images.example.com
dig TXT _convertly-verify.images.example.com

For production traffic, wait for the dashboard to show Verified before switching application URLs.

Set up Image CDN

Create an endpoint, select its access policy, and deliver the first asset.

URL structure

Compare Convertly-hosted and custom-domain URL shapes.

Signed delivery

Protect private delivery with expiring signatures.

Transforms

Review every supported delivery parameter.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Before you start

Add a domain

Automatic Cloudflare setup

Automatic verification

Use the domain

Public and signed endpoints

Changing or removing a domain

Troubleshooting

Set up Image CDN

URL structure

Signed delivery

Transforms

​Before you start

​Add a domain

​Automatic Cloudflare setup

​Automatic verification

​Use the domain

​Public and signed endpoints

​Changing or removing a domain

​Troubleshooting

​Related documentation

Set up Image CDN

URL structure

Signed delivery

Transforms

Before you start

Add a domain

Automatic Cloudflare setup

Automatic verification

Use the domain

Public and signed endpoints

Changing or removing a domain

Troubleshooting

Related documentation