Manage site domains and aliases

A WP Cloud site has one primary domain and can have secondary domains. Requests to a secondary domain normally redirect to the primary domain. Host partners can use the WP Cloud API to check whether a domain is available, manage secondary domains, retrieve suggested DNS addresses, and change the primary domain.

The examples use these placeholders:

• <api-key> is a WP Cloud API key with access to the site.
• <client> is the host client’s WP Cloud identifier.
• <site-id> is the site’s Atomic Site ID.
• <current-domain> is the site’s current primary domain.
• <new-domain> is the domain being added or promoted.

Keep the Atomic Site ID as the site’s permanent identifier in partner systems. The site ID does not change when its primary domain changes.

Check whether WP Cloud can host the domain

Before creating a site or adding a domain, use the Validate Domain Eligibility endpoint:

curl --fail-with-body --silent --show-error \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/check-can-host-domain/<client>/<new-domain>"Code language: HTML, XML (xml)Copy

An available domain returns allowed: true:

{
  "message": "OK",
  "data": {
    "allowed": true
  }
}Code language: JSON / JSON with Comments (json)Copy

The check returns false for a domain that is already hosted on WordPress.com or WP Cloud, even when the domain is valid. Check eligibility before site creation as well as before adding a secondary domain to avoid a domain collision.

Add, list, or remove a secondary domain

Use the Manage Site Aliases endpoint to add a secondary domain. This example finds the site by its Atomic Site ID:

curl --fail-with-body --silent --show-error \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/site-alias/<client>/<site-id>/add/<new-domain>"Code language: HTML, XML (xml)Copy

A successful response includes the site’s secondary domains:

{
  "message": "OK",
  "data": {
    "domains": ["www.example.com"]
  }
}Code language: JSON / JSON with Comments (json)Copy

List the current secondary domains with the list action:

curl --fail-with-body --silent --show-error \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/site-alias/<client>/<site-id>/list"Code language: HTML, XML (xml)Copy

Remove a secondary domain with the remove action:

curl --fail-with-body --silent --show-error \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/site-alias/<client>/<site-id>/remove/<new-domain>"Code language: HTML, XML (xml)Copy

The API does not allow the primary domain to be removed as an alias. Change the primary domain first when the old primary domain should be removed from the site.

WP Cloud secondary domains redirect to the primary domain. They do not make WordPress generate page and post links for each secondary hostname. A partner that needs different domain behavior must provide that behavior separately and account for WordPress’s absolute URLs.

Control alias canonicalization

WP Cloud normally canonicalizes secondary domains by redirecting them to the primary domain. The canonicalize_aliases site-meta value controls this behavior.

Set canonicalize_aliases to false only when the WordPress installation must serve its secondary domains directly. The main use case is a domain-based WordPress multisite network, where different domains are mapped to different subsites.

Disabling canonicalization removes WP Cloud’s normal alias-to-primary redirects. WordPress, a plugin, or partner-maintained code must then handle any required www, non-www, or domain-to-domain redirects. The setting does not define individual redirect rules; it determines whether WP Cloud redirects all secondary domains to the primary domain before WordPress handles the request. Setting it back to true on a site that serves several domains redirects those aliases to the primary domain with HTTP 301 responses.

Change the value with the Site Meta endpoint. Do not disable it for an ordinary site when every secondary domain should continue redirecting to the primary domain.

Retrieve suggested DNS addresses

Use the Get Client IP Addresses endpoint to retrieve the WP Cloud range and suggested A record addresses for a domain:

curl --fail-with-body --silent --show-error \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/get-ips/<client>/<new-domain>"Code language: HTML, XML (xml)Copy

Example response:

{
  "message": "OK",
  "data": {
    "ips": ["192.0.78.128/25"],
    "suggested": ["192.0.78.150", "192.0.78.200"]
  }
}Code language: JSON / JSON with Comments (json)Copy

Use the suggested addresses for the domain’s A records unless the host client’s WP Cloud configuration specifies otherwise. Domain verification records explains the TXT record WP Cloud may require when another host client already uses the domain.

Change the primary domain

Add the new domain as a secondary domain and configure its DNS before promoting it. Confirm that WP Cloud can serve the domain and provision its TLS certificate.

Send a POST request to the Update Site Domain endpoint:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Auth: <api-key>" \
  "https://atomic-api.wordpress.com/api/v1.0/update-site-domain/<client>/<site-id>/<new-domain>/keep"Code language: HTML, XML (xml)Copy

The response identifies the queued job, the site, and both domains:

{
  "message": "OK",
  "data": {
    "job_id": 2345,
    "atomic_site_id": 5678,
    "domain_name": "www.example.com",
    "old_domain_name": "example.com"
  }
}Code language: JSON / JSON with Comments (json)Copy

The keep value retains the old primary domain as a secondary domain. Pass false instead when the old domain should be removed. Check the returned job with the Get Job Statuses endpoint before updating systems that depend on the new primary domain.

Changing the WP Cloud primary domain does not replace every domain stored by WordPress, plugins, themes, or partner systems. Update any affected URLs as part of the host partner’s domain-change process.