The Static Hosting Custom Domains API lets you list, add, check, and remove the custom domains of a [Static Hosting](Article: 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](Article: static-hosting-custom-domains).

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](https://api.deployhq.com/docs).

# List custom domains

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

## URL

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

## HTTP Method

```text
GET
```

## Example cURL request

```bash
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

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

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

## HTTP Method

```text
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

```bash
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`:

```json
{
  "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](#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`:

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

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

If the account has made too many changes, the API returns HTTP `429`. See [Rate limit](#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](#list-custom-domains) a few seconds later.

## URL

```text
/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

```text
POST
```

## Example cURL request

```bash
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

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

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

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

```text
/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

```text
DELETE
```

## Example cURL request

```bash
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

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

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

```json
{
  "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](#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](#rate-limit). A domain that cannot be set up afterwards appears with the status `failed`, as described in [Getting the TXT record](#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:

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