Custom Domains
Serve one project's media from a customer-owned hostname. Starter includes 1 hostname per account and Pro 3. Add the CNAME target returned by the API; Cloudflare provisions and renews HTTPS automatically.
The Custom domain object
A customer-owned hostname attached to one project. It is ready only when both hostname and certificate statuses are active.
Properties
| Property | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string | Custom-domain id ( | ||||||||||||
project_id | string | Project whose media this hostname serves. | ||||||||||||
hostname | string (hostname) | |||||||||||||
status | string | Convenience status: | ||||||||||||
hostname_status | string | Cloudflare hostname validation status. | ||||||||||||
certificate_status | string | Cloudflare certificate issuance status. | ||||||||||||
ready | boolean | True only when HTTPS traffic is production-ready. | ||||||||||||
cname_target | string (hostname) | Set the custom hostname's CNAME to this target. | ||||||||||||
ownership_verification | object nullable | Additional TXT ownership record when Cloudflare requires one; otherwise null. | ||||||||||||
Child properties of | ||||||||||||||
| Property | Type | Description |
|---|---|---|
type | string | |
name | string | |
value | string |
created_atupdated_at{
"id": "dom_abc123",
"project_id": "proj_abc123",
"hostname": "media.example.com",
"status": "pending",
"hostname_status": "pending",
"certificate_status": "pending_validation",
"ready": false,
"cname_target": "custom.pvcdn.dev",
"ownership_verification": {
"type": "TXT",
"name": "_cf-custom-hostname.media.example.com",
"value": "verification-token"
},
"created_at": "2026-11-17T09:30:00Z",
"updated_at": "2026-11-17T09:30:00Z"
}List custom domains
GET /v1/custom-domains
Lists the custom hostnames attached to the calling key's project or the dashboard's active project. The account-wide plan limit and current total are returned in meta.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Responses
- 200
Project custom domains and account limit
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
custom_domain_management_forbidden: publishable keys cannot manage custom domains.account_suspended: the account is suspended.
curl https://api.pixelvault.dev/v1/custom-domains \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": [
{
"id": "dom_abc123",
"project_id": "proj_abc123",
"hostname": "media.example.com",
"status": "pending",
"hostname_status": "pending",
"certificate_status": "pending_validation",
"ready": false,
"cname_target": "custom.pvcdn.dev",
"ownership_verification": {
"type": "TXT",
"name": "_cf-custom-hostname.media.example.com",
"value": "verification-token"
},
"created_at": "2026-11-17T09:30:00Z",
"updated_at": "2026-11-17T09:30:00Z"
}
],
"meta": {
"limit": 1,
"total": 1,
"project_total": 1,
"cname_target": "custom.pvcdn.dev"
}
} Add a custom domain
POST /v1/custom-domains
Adds a hostname to the project and starts hostname validation plus automatic certificate issuance. Add the returned CNAME record, then call refresh_custom_domain until ready is true. Custom domains are account-limited: 0 Free, 1 Starter, 3 Pro.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
hostname | string (hostname) | Required |
Responses
- 201
Custom domain created; DNS setup can begin
- 400
invalid_jsonorvalidation_error: hostname is missing or not a valid ASCII DNS hostname. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
custom_domains_require_paid_plan: upgrade to Starter or Pro. - 403
custom_domain_management_forbidden,email_verification_requiredoraccount_suspended. - 409
custom_domain_exists,custom_domain_conflictorcustom_domain_limit_reached. - 502
custom_domain_provisioning_failed: Cloudflare rejected or could not complete the provisioning request. - 503
custom_domains_unavailable: the provisioning integration is not configured.
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"}' {
"data": {
"id": "dom_abc123",
"project_id": "proj_abc123",
"hostname": "media.example.com",
"status": "pending",
"hostname_status": "pending",
"certificate_status": "pending_validation",
"ready": false,
"cname_target": "custom.pvcdn.dev",
"ownership_verification": {
"type": "TXT",
"name": "_cf-custom-hostname.media.example.com",
"value": "verification-token"
},
"created_at": "2026-11-17T09:30:00Z",
"updated_at": "2026-11-17T09:30:00Z"
},
"meta": {
"limit": 1
}
} Refresh domain status
POST /v1/custom-domains/{id}/refresh
Asks Cloudflare to retry validation and returns the latest hostname and certificate statuses.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Custom-domain id ( |
Responses
- 200
Latest state
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
custom_domain_management_forbiddenoraccount_suspended. - 404
custom_domain_not_found: no custom domain with this id belongs to the project. - 502
custom_domain_provisioning_failed: Cloudflare could not refresh validation. - 503
custom_domains_unavailable: the provisioning integration is not configured.
curl -X POST https://api.pixelvault.dev/v1/custom-domains/id/refresh \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"id": "dom_abc123",
"project_id": "proj_abc123",
"hostname": "media.example.com",
"status": "pending",
"hostname_status": "pending",
"certificate_status": "pending_validation",
"ready": false,
"cname_target": "custom.pvcdn.dev",
"ownership_verification": {
"type": "TXT",
"name": "_cf-custom-hostname.media.example.com",
"value": "verification-token"
},
"created_at": "2026-11-17T09:30:00Z",
"updated_at": "2026-11-17T09:30:00Z"
}
} Remove a custom domain
DELETE /v1/custom-domains/{id}
Stops hostname routing immediately, removes the Cloudflare custom hostname and certificate, then deletes the PixelVault record. Remove the customer DNS record afterward.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Custom-domain id ( |
Responses
- 200
Custom domain removed
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
custom_domain_management_forbiddenoraccount_suspended. - 404
custom_domain_not_found: no custom domain with this id belongs to the project. - 502
custom_domain_provisioning_failed: Cloudflare could not remove the hostname. - 503
custom_domains_unavailable: the provisioning integration is not configured.
curl -X DELETE https://api.pixelvault.dev/v1/custom-domains/id \
-H "Authorization: Bearer $PIXELVAULT_API_KEY"