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

[API reference](/docs/api/)

# 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](#object)
-   GET [List custom domains](#list_custom_domains)
-   POST [Add a custom domain](#create_custom_domain)
-   POST [Refresh domain status](#refresh_custom_domain)
-   DELETE [Remove a custom domain](#delete_custom_domain)

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

The Custom domain object properties

Property

Type

Description

`id`

string

Custom-domain id (`dom_` prefix).

`project_id`

string

Project whose media this hostname serves.

`hostname`

string (hostname)

`status`

string

Convenience status: `active` only when hostname and certificate are both active; otherwise the hostname 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 `ownership_verification`

Properties of ownership\_verification

Property

Type

Description

`type`

string

One of: `TXT`

`name`

string

`value`

string

`created_at`

string (date-time)

`updated_at`

string (date-time)

The Custom domain object

```
{
  "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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    `custom_domain_management_forbidden`: publishable keys cannot manage custom domains. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    

Request

curlNode.jsPython

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

Response 200

```
{
  "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`](/docs/api/custom-domains/#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

`application/json`, required

Request body

Name

Type

Required

Description

`hostname`

string (hostname)

Required

max length 253

### Responses

-   201
    
    Custom domain created; DNS setup can begin
    
-   400
    
    [`invalid_json`](/docs/errors/#invalid_json) or [`validation_error`](/docs/errors/#validation_error): hostname is missing or not a valid ASCII DNS hostname.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#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_required`](/docs/errors/#email_verification_required) or [`account_suspended`](/docs/errors/#account_suspended).
    
-   409
    
    `custom_domain_exists`, `custom_domain_conflict` or `custom_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.
    

Request

curlNode.jsPython

```
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"}'
```

Response 201

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Custom-domain id (`dom_` prefix).

### Responses

-   200
    
    Latest state
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    `custom_domain_management_forbidden` or [`account_suspended`](/docs/errors/#account_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.
    

Request

curlNode.jsPython

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

Response 200

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Custom-domain id (`dom_` prefix).

### Responses

-   200
    
    Custom domain removed
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    `custom_domain_management_forbidden` or [`account_suspended`](/docs/errors/#account_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.
    

Request

curlNode.jsPython

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

Response 200

Custom domain removed
