Custom Domain

Use the Custom Domain Resource API to attach a custom image delivery hostname to an Imgwire Environment.

Overview

Each Environment can have one custom domain. A custom domain lets delivered image URLs use your hostname instead of the default Imgwire CDN hostname after DNS and certificate validation complete.

Custom domains must be subdomains, such as cdn.example.com or images.example.com. You need access to the domain's DNS settings. Creating a custom domain returns the CNAME records you need to add for routing and domain control validation.

Endpoints

Method	Path	Purpose
GET	/api/v1/custom_domain/	Retrieve the Environment's custom domain
POST	/api/v1/custom_domain/	Create a custom domain
DELETE	/api/v1/custom_domain/	Delete the custom domain
POST	/api/v1/custom_domain/test_connection	Re-check DNS and certificate connection status

For programmatic backend integrations, manage custom domains with a Server API Key.

Create a custom domain

curl https://api.imgwire.dev/api/v1/custom_domain/ \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"images.example.com"}'

Example response:

{
  "id": "e370a4a1-b6c0-4723-9a32-d40f00d3ad4f",
  "environment_id": "26f80c13-48bd-4bb9-866e-5e9392b11a6a",
  "hostname": "images.example.com",
  "cname_record": "images.example.com",
  "cname_value": "cdn-proxy.imgwire.dev",
  "dcv_cname_record": "_acme-challenge.images.example.com",
  "dcv_cname_value": "images.example.com",
  "certificate_status": "PENDING",
  "status": "PENDING",
  "last_verified_at": null,
  "created_at": "2026-05-09T18:30:00Z",
  "updated_at": "2026-05-09T18:30:00Z"
}

Add the returned CNAME records in your DNS provider. The exact cname_value and dcv_cname_value come from the API response for your Environment, so use the values returned by your request.

Check connection status

After updating DNS, call test_connection to re-check the custom domain:

curl https://api.imgwire.dev/api/v1/custom_domain/test_connection \
  -X POST \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

The response is the current CustomDomain record.

Status fields

Field	Values	Meaning
status	PENDING, CONNECTED, FAILED	Whether the hostname is connected for delivery
certificate_status	PENDING, ACTIVE, FAILING	Whether the SSL certificate is ready
last_verified_at	date-time or null	When Imgwire last observed a verified domain or certificate status

Constraints

• Each Environment can have one custom domain.
• Custom domains must be subdomains, such as cdn.example.com; do not use an apex/root domain such as example.com.
• A hostname can be claimed by only one custom domain.
• You need DNS access for the hostname you create.
• Your organization plan must have custom domains enabled.

Best practices

• Use a dedicated image hostname such as images.example.com or cdn.example.com.
• Add both returned DNS records before expecting the domain to connect.
• Keep using the default Imgwire CDN URL until status is CONNECTED and certificate_status is ACTIVE.
• Re-run test_connection after DNS changes instead of repeatedly deleting and recreating the domain.

Common mistakes

• Creating a custom domain without DNS access.
• Trying to add multiple custom domains to the same Environment.
• Using the hostname before certificate validation is active.
• Reusing a hostname that is already claimed by another Environment.

Related pages

• Troubleshooting Custom Domains
• Images
• API Reference

Last updated at: May 9, 2026