<!-- Markdown twin of https://pixelvault.dev/docs/guides/custom-domains/ -->

# Serve media from your own domain

Last updated: November 2026

Attach a hostname such as `media.example.com` to one project. PixelVault keeps storage and delivery unchanged, but public URLs become `https://media.example.com/<asset_id>.<ext>`. Starter includes 1 custom domain per account; Pro includes 3.

## 1\. Add the hostname

Use a secret API key from the project the hostname should serve. The account email must be verified.

```
curl -X POST https://api.pixelvault.dev/v1/custom-domains \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"media.example.com"}'
```

The response contains the domain id, its current hostname and certificate statuses, and the authoritative `cname_target`. You can also add it from [Dashboard → Settings → Custom domains](/dashboard/settings/domains/).

## 2\. Create the CNAME

At the DNS provider for your domain, create this record. Use DNS-only or unproxied mode during setup when your provider offers a proxy toggle.

```
Type    Name                 Target
CNAME   media.example.com    custom.pvcdn.dev
```

Use the exact target returned by the API rather than copying this example. Some hostnames also receive an `ownership_verification` TXT record; create it when present.

## 3\. Wait for HTTPS

DNS propagation and certificate issuance are separate. The hostname is ready only when both `hostname_status` and `certificate_status` are `active`, making `ready` true.

```
curl -X POST https://api.pixelvault.dev/v1/custom-domains/dom_abc123/refresh \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Do not treat a successful TLS handshake alone as readiness: another matching certificate may answer before the custom-hostname certificate finishes provisioning.

## 4\. Use the custom URL

Canonical URL

Custom-domain URL

`img.pixelvault.dev/proj_abc/img_123.jpg`

`media.example.com/img_123.jpg`

`img.pixelvault.dev/proj_abc/blog/img_123.jpg`

`media.example.com/blog/img_123.jpg`

Every media response keeps the canonical `url` and includes `branded_url` when a custom domain is ready. Use that returned value rather than rebuilding a URL yourself; private signatures and image transform query parameters are preserved. The CLI can manage the domain and select the branded result:

```
pixelvault domains add media.example.com
# Add the returned DNS records, then refresh until ready=true
pixelvault domains refresh dom_abc123
# Print the branded URL when ready; falls back to the canonical URL
pixelvault upload photo.jpg --branded
```

## Remove a hostname

[Delete the custom domain](/docs/api/custom-domains/#delete_custom_domain) in PixelVault first. Routing stops immediately and Cloudflare removes its certificate. Then remove the customer DNS record. A project cannot be deleted while it still has custom domains.

## API operations

-   [List custom domains](/docs/api/custom-domains/#list_custom_domains)
-   [Add a custom domain](/docs/api/custom-domains/#create_custom_domain)
-   [Refresh validation status](/docs/api/custom-domains/#refresh_custom_domain)
-   [Remove a custom domain](/docs/api/custom-domains/#delete_custom_domain)
