Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

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

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

Request
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 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 or validation_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_required or 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
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: 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 or 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
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: 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 or 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
curl -X DELETE https://api.pixelvault.dev/v1/custom-domains/id \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200

Custom domain removed