Last updated on 18th November 2026

Static Hosting Custom Domains API

The Static Hosting Custom Domains API lets you list, add, check, and remove the custom domains of a Static Hosting site. Custom domains are managed on the Static Hosting server that owns the site, which can be a project server or a global server. For how custom domains work and how to set up DNS, see Custom domains for Static Hosting.

Custom domains are available on paid plans, including trials. A site can have up to two custom domains: a domain and its www counterpart (for example example.com and www.example.com). The first one added is the primary; the other redirects to it.

Every endpoint is available under two paths, and behaves the same on both:

Server Path
Project server /projects/:project_id/servers/:server_id/custom_domains
Global server /global_servers/:global_server_id/custom_domains

Replace :project_id with the permalink or identifier of the project, and :server_id or :global_server_id with the identifier of the Static Hosting server. The examples below use the project server path.

On a project server, every endpoint needs permission to edit the project's servers. On a global server, listing is open to any user of the account, and adding, checking, or removing a domain needs an account administrator. A server that is not a Static Hosting server returns HTTP 404.

Tip: You can explore and test these endpoints interactively using our OpenAPI documentation.

List custom domains

Returns the custom domains of a Static Hosting site, including the DNS records you need to publish for each one.

URL

/projects/:project_id/servers/:server_id/custom_domains
/global_servers/:global_server_id/custom_domains

HTTP Method

GET

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:api-key \
https://test.deployhq.com/projects/my-project/servers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/custom_domains

Example Response

[
  {
    "identifier": "0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90",
    "hostname": "www.example.com",
    "primary": true,
    "status": "active",
    "registering": false,
    "ssl_status": "active",
    "verification_errors": [],
    "activated_at": "2026-11-05T10:15:00.000Z",
    "created_at": "2026-11-05T10:00:00.000Z",
    "dns_records": [
      {
        "type": "CNAME",
        "name": "www.example.com",
        "value": "customers.deployhq-sites.com"
      },
      {
        "type": "TXT",
        "name": "<txt-record-name>",
        "value": "<txt-record-value>"
      }
    ]
  }
]

The TXT record name and value are unique to each domain; the placeholders above stand in for the values returned for your domain.

Add a custom domain

Adds a custom domain to a Static Hosting site. The domain is created straight away and set up in the background, so the response returns before its DNS records are complete. The domain starts as pending and becomes active automatically once both DNS records in dns_records are published and an SSL certificate has been issued.

URL

/projects/:project_id/servers/:server_id/custom_domains
/global_servers/:global_server_id/custom_domains

HTTP Method

POST

Parameters

Parameter Description
custom_domain[hostname] The hostname to add, without https:// (for example www.example.com). Required.
custom_domain[with_counterpart] Set to true to also add the other half of the apex and www pair in the same request. Optional.

with_counterpart only applies to a site that has no custom domains yet other than expired ones, and only when hostname is an apex domain or www. followed by one. The hostname you send is the primary, and the counterpart redirects to it.

Example cURL request

curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:api-key \
-d '{"custom_domain":{"hostname":"example.com","with_counterpart":true}}' \
https://test.deployhq.com/projects/my-project/servers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/custom_domains

Example Response

A successful request returns HTTP 201:

{
  "identifier": "0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90",
  "hostname": "example.com",
  "primary": true,
  "status": "pending",
  "registering": true,
  "ssl_status": null,
  "verification_errors": [],
  "activated_at": null,
  "created_at": "2026-11-05T10:00:00.000Z",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "example.com",
      "value": "customers.deployhq-sites.com"
    }
  ],
  "counterpart": {
    "identifier": "7b1e4d90-2c3a-4f58-b6d7-1a9c0e3f5d21",
    "hostname": "www.example.com",
    "primary": false,
    "status": "pending",
    "registering": true,
    "ssl_status": null,
    "verification_errors": [],
    "activated_at": null,
    "created_at": "2026-11-05T10:00:00.000Z",
    "dns_records": [
      {
        "type": "CNAME",
        "name": "www.example.com",
        "value": "customers.deployhq-sites.com"
      }
    ]
  },
  "counterpart_errors": []
}

counterpart is null when it was not requested, the hostname is not eligible, or it could not be added. In the last case counterpart_errors says why. A counterpart that cannot be added never undoes the domain you asked for.

Getting the TXT record

While registering is true, dns_records holds only the CNAME record. To get the ownership TXT record, poll List custom domains every few seconds until registering is false for the domain. The TXT record is then listed in dns_records. If its name or value is still null, list the domains again shortly. Stop polling if the domain's status becomes failed: verification_errors gives the reason and dns_records is empty when the domain could not be set up.

If the domain cannot be set up, registering becomes false, status becomes failed, and verification_errors gives the reason. A setup problem is reported this way rather than as an error response to the add request. To try again, remove the domain and add it again.

For an apex domain such as example.com, publish the CNAME record as an ALIAS, ANAME, or CNAME flattening record at your DNS provider, because plain CNAME records are not allowed at the apex.

Errors

If your account is not on a paid plan or trial, the API returns HTTP 403:

{
  "error": "Custom domains are only available on paid plans",
  "error_code": "paid_plan_required",
  "hint": "Upgrade your plan at https://test.deployhq.com/packages"
}

If the hostname is invalid or already in use, the site cannot take another custom domain, or the account already has 10 custom domains waiting for verification, the API returns HTTP 422 with a list of error messages:

{
  "errors": ["Hostname is not a valid domain name"]
}

If the account has made too many changes, the API returns HTTP 429. See Rate limit.

Check a custom domain now

Asks for a pending custom domain to be checked now instead of on the next scheduled check, which happens every few minutes. The check runs in the background, so the API returns HTTP 202. Read the outcome from List custom domains a few seconds later.

URL

/projects/:project_id/servers/:server_id/custom_domains/:identifier/refresh
/global_servers/:global_server_id/custom_domains/:identifier/refresh

Replace :identifier with the identifier of the custom domain.

HTTP Method

POST

Example cURL request

curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:api-key \
https://test.deployhq.com/projects/my-project/servers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/custom_domains/0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90/refresh

Example Response

{
  "status": "check_requested",
  "identifier": "0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90"
}

Errors

Only pending domains can be checked. For a domain in any other status, the API returns HTTP 422:

{
  "error": "www.example.com is not waiting for verification, so there is nothing to check"
}

A domain cannot be checked again within 60 seconds of its last check. The API then returns HTTP 429, with retry_after in seconds and a matching Retry-After header:

{
  "error": "This domain was checked moments ago. Try again shortly.",
  "retry_after": 42
}

Remove a custom domain

Removes a custom domain from a Static Hosting site. Removal happens in the background, so the API returns HTTP 202 and the domain may still be listed for a short while. Once the domain is removed it stops serving your site; remove its DNS records at your DNS provider afterwards.

URL

/projects/:project_id/servers/:server_id/custom_domains/:identifier
/global_servers/:global_server_id/custom_domains/:identifier

Replace :identifier with the identifier of the custom domain.

HTTP Method

DELETE

Example cURL request

curl -X DELETE \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:api-key \
https://test.deployhq.com/projects/my-project/servers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/custom_domains/0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90

Example Response

{
  "status": "removal_requested",
  "identifier": "0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90"
}

Adding a domain when creating a server

You can ask for a custom domain in the request that creates a Static Hosting server, on both POST /projects/:project_id/servers and POST /global_servers. Pass these inside the top-level hosted_website_attributes:

Parameter Description
custom_domain_hostname The hostname to add, without https://. Optional.
custom_domain_with_counterpart Set to true to also add the other half of the apex and www pair. Optional.

Example cURL request

curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:api-key \
-d '{"server":{"name":"marketing-site","protocol_type":"static_hosting"},"hosted_website_attributes":{"subdomain":"marketing-site","spa_mode":false,"custom_domain_hostname":"example.com","custom_domain_with_counterpart":true}}' \
https://test.deployhq.com/projects/my-project/servers

Response

The response to creating a Static Hosting server always includes two extra fields, alongside the usual server fields. Both are empty when no domain was requested.

{
  "custom_domains": [
    {
      "identifier": "0f3c9a52-6d1e-4b7a-9c2f-8e5d4a1b7c90",
      "hostname": "example.com",
      "primary": true,
      "status": "pending",
      "registering": true,
      "ssl_status": null,
      "verification_errors": [],
      "activated_at": null,
      "created_at": "2026-11-05T10:00:00.000Z",
      "dns_records": [
        {
          "type": "CNAME",
          "name": "example.com",
          "value": "customers.deployhq-sites.com"
        }
      ]
    }
  ],
  "custom_domain_errors": []
}

custom_domains lists the domains added, in the same format as List custom domains, and custom_domain_errors says why a domain or its counterpart could not be added.

A hostname that fails validation is refused before the server is created, and the API returns HTTP 422. Otherwise a domain that cannot be added never fails the create: the server is created, and the reason is in custom_domain_errors. This applies to accounts that are not on a paid plan or trial and to accounts over the rate limit. A domain that cannot be set up afterwards appears with the status failed, as described in Getting the TXT record.

Rate limit

An account can make at most 10 requests per hour that add or remove a custom domain, across all of its sites. A pair added with with_counterpart counts as one request, a domain requested when creating a server counts as one request, and a refused request still counts. Checking a domain does not count.

Over the limit, the API returns HTTP 429, with a matching Retry-After header. retry_after is the longest you may need to wait, in seconds:

{
  "error": "Too many requests to add or remove custom domains (at most 10 per hour). Try again later.",
  "retry_after": 3600
}

Field reference

Field Description
identifier Unique identifier of the custom domain. Use it to check or remove the domain.
hostname The custom domain.
primary true for the primary domain. The other domain redirects to it.
status One of pending, active, failed, or expired. A domain still pending or failed 7 days after it was added expires and must be added again.
registering true while the domain is pending and still being set up. While it is true, dns_records holds only the CNAME record.
ssl_status Status of the domain's SSL certificate. May be null before a certificate has been issued.
verification_errors Messages from the most recent DNS check, if any, or the reason a domain could not be set up.
activated_at When the domain became active. null until then.
created_at When the domain was added.
dns_records The DNS records to publish at your DNS provider: a CNAME and a TXT record, each with type, name, and value. The TXT record is listed once registering is false. Empty when the domain could not be set up.

Statuses

Status Description
pending Waiting for both DNS records to be published and verified
active Verified, with an SSL certificate issued; the site is served on this domain
failed The domain could not be set up or verified; the reason is in verification_errors. Check the DNS records, then remove it and add it again. Expires 7 days after it was added
expired The domain was not verified within 7 days; remove it and add it again