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