Skip to content

Domains

All domains will be routed through our high performance CDN provider, bunny. Each domain can be connected by changing your nameservers, or by setting a cname record.

These endpoints manage the hostnames attached to WordPress sites. For registrar operations (registering/transferring a TLD) see Domain Registration. OAuth scopes: lookup/query require domains:read; per-site domain writes require sites:write.

Lookup and Query

List All Domains

List all domains accessible to a user.

GET /api/domains

Params (optional)
  • page: Integer | page number (default: 1)
  • per_page: Integer | records per page (default: 50, max: 100)
Returned Params
  • domains: Array
    • id: String
    • hostname: String
    • site_id: String
    • account_id: String
    • dns_zone: Object | associated dns zone
      • id: String
      • name: String
      • dnssec: Boolean
      • dnssec_data: Object (nil if dnssec = false)
      • created_at: DateTime
      • updated_at: DateTime
      • account: Object
        • id: String
        • name: String
    • dns_zone_records: Array | associated dns records
      • id: String
      • record_type: Integer
      • ttl: Integer
      • value: String
      • name: String
      • priority: Integer
      • weight: Integer
      • port: Integer
      • flags: String
      • record_tag: String
      • comment: String
      • created_at: DateTime
      • updated_at: DateTime

Load Domain by ID

GET /api/domains/:id

Returns a single domain object with the same fields as a list entry.

Search by Domain Name

POST /api/domains/query

This is a helper endpoint to find a domain without knowing its ID.

The param q supports substring matching anywhere in the hostname. For example:

  • Searching for example matches example.com;
  • Searching for domain matches mydomain.com.
Params
  • q: String

Returns the same shape as List All Domains.

Check if a domain is available

POST /api/domains/available

This will check if the domain is valid, and if it already exists in our system.

Params
  • hostname: String

Use the HTTP status code to determine availability / validity:

  • HTTP 200: Exists and not available
  • HTTP 422: Not a valid domain, or missing hostname param.
  • HTTP 404: Does not exist — valid and available.
Returned Params
  • status: String

Site Endpoints

List all domains for a site

GET /api/sites/:site_id/domains

Returned Params
  • domains: Array
    • id: String
    • hostname: String
    • dns_zone: Object | associated dns zone
    • dns_zone_records: Array | associated dns records
    • created_at: DateTime
    • updated_at: DateTime

Create a Domain

POST /api/sites/:site_id/domains

If no domain exists for a site, this will be automatically configured as the primary domain. Provisioning runs asynchronously — returns 202 and creates a task.

provision_method must be the exact string dns to provision via nameservers; any other value (or omission) is treated as cname.

Params
  • domain: String (required) | FQDN
  • provision_method: String | the exact string dns, otherwise cname
Errors
  • 400 {"errors":["Domain can't be blank."]} | domain blank/missing
  • 422 | domain invalid or could not be saved (see errors array)
Returned params for DNS (provision_method = dns)
  • id: String
  • ns1: String | first nameserver (from the site's account)
  • ns2: String | second nameserver (from the site's account)
Returned params for cname (default)
  • id: String
  • cname: String

Promote a domain

PATCH /api/sites/:site_id/domains/:id

This takes no parameters and will promote the requested domain to the primary domain. The existing primary domain will become an alias. Returns 202.

Remove

This will remove the domain. If it is the primary domain, the site will be updated to use the default temporary url. It's recommended to first promote your new domain to the primary domain before deleting it. Returns 202.

DELETE /api/sites/:site_id/domains/:id

Pre-provision SSL Certificate (External DNS)

Obtain a Bunny SSL certificate (optionally wildcard) via a DNS-01 challenge for a hostname whose DNS is hosted elsewhere — before pointing it at SuperSpace.

Requires CDN active for the site, else 409 cdn_not_active. Scope: sites:read for status; the request/complete steps require sites:write and site write/modify permission. The request/complete steps proxy a Bunny call — an upstream Bunny failure returns 502.

The flow:

  1. POST .../request_certificate returns a DNS-01 TXT challenge to add at your DNS.
  2. Add the TXT record at your DNS provider.
  3. POST .../complete_certificate — Bunny validates and issues the certificate.

Certificate Status

GET /api/sites/:site_id/domains/:id/certificate

Returned Params
  • provision_type: String | null, http01, dns01_external, or custom
  • wildcard: Boolean
  • challenge: Object | null | the DNS-01 TXT record(s) to add (while pending)
  • requested_at: Timestamp | null
  • issued_at: Timestamp | null
  • active: Boolean

Request Certificate (step 1)

POST /api/sites/:site_id/domains/:id/request_certificate

Params
  • wildcard: Boolean

Returns the DNS-01 TXT challenge to add at your DNS.

Complete Certificate (step 2)

POST /api/sites/:site_id/domains/:id/complete_certificate

Call once the TXT record is live; Bunny validates and issues the certificate.