Skip to main content
The Starhost Domains API lets you attach custom domains to your Starhost sites entirely through code. After adding a domain, the API returns the DNS records you need to configure with your domain registrar. Once the records propagate, Starhost verifies the domain automatically and provisions an SSL certificate. You can also query the current status of any domain or remove it when it is no longer needed. This page covers the following endpoints:
  • POST /starhost/domains — Add a custom domain to a site
  • GET /starhost/domains/{domain} — Get domain status
  • DELETE /starhost/domains/{domain} — Remove a domain from a site

​
Add a custom domain

Connect a custom domain to one of your Starhost sites. The API returns the DNS records you must add at your registrar to complete verification. Endpoint 
POST https://api.verbosec.com/v1/starhost/domains

​
Request parameters

​
site_id
string
required
The unique identifier of the Starhost site you want to attach the domain to. You can find this in the Verbosec Cloud dashboard under your site’s settings.
​
domain
string
required
The custom domain name to add — for example, "yourdomain.com" or "app.yourdomain.com". Do not include https:// or a trailing slash.

​
Example request

add-domain.sh
curl -X POST https://api.verbosec.com/v1/starhost/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_abc001",
    "domain": "yourdomain.com"
  }'

​
Example response

add-domain-response.json
{
  "domain": "yourdomain.com",
  "site_id": "site_abc001",
  "status": "pending_verification",
  "dns_records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.0.2.1"
    },
    {
      "type": "CNAME",
      "name": "www",
      "value": "yourdomain.com"
    }
  ],
  "created_at": "2025-01-15T12:00:00Z"
}
Add all records listed in dns_records to your domain registrar’s DNS settings. Starhost checks for the records automatically and updates the domain status to verified once propagation is confirmed. DNS propagation can take up to 48 hours depending on your registrar.

​
Get domain status

Retrieve the current verification and SSL status of a domain you have added to a site. Poll this endpoint after adding DNS records to confirm when verification is complete. Endpoint 
GET https://api.verbosec.com/v1/starhost/domains/{domain}

​
Path parameters

​
domain
string
required
The domain name to query — for example, yourdomain.com. This must match the domain you used when adding it.

​
Example request

get-domain.sh
curl -X GET https://api.verbosec.com/v1/starhost/domains/yourdomain.com \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

get-domain-response.json
{
  "domain": "yourdomain.com",
  "site_id": "site_abc001",
  "status": "verified",
  "ssl": "active",
  "created_at": "2025-01-15T12:00:00Z"
}

​
Domain status values

StatusDescription
pending_verificationThe domain has been added but the required DNS records have not yet been detected.
verifiedDNS records were confirmed and the domain is live. An SSL certificate has been provisioned.
failedVerification failed. Check that the DNS records are correctly configured and try again.
SSL statusDescription
inactiveSSL has not yet been provisioned, typically because verification is still pending.
activeAn SSL certificate is active and HTTPS is enforced for the domain.
errorSSL provisioning encountered an error. Contact Verbosec support if this persists.

​
Remove a domain

Detach a custom domain from your Starhost site and release it from your account. This action is irreversible — you will need to add the domain again if you want to reconnect it later. Endpoint 
DELETE https://api.verbosec.com/v1/starhost/domains/{domain}

​
Path parameters

​
domain
string
required
The domain name to remove — for example, yourdomain.com.

​
Example request

delete-domain.sh
curl -X DELETE https://api.verbosec.com/v1/starhost/domains/yourdomain.com \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

A successful delete returns 204 No Content with an empty response body. 
HTTP/1.1 204 No Content
Removing a domain immediately stops Starhost from serving traffic to it. Make sure you have updated your DNS records before removing a domain that is receiving live traffic, to avoid downtime.

​
Error responses

Returned when a required parameter such as site_id or domain is absent from the request body.
400-response.json
{
  "error": {
    "code": "missing_required_field",
    "message": "The 'domain' field is required."
  }
}
Returned when the domain in the path is not associated with any site on your account.
404-response.json
{
  "error": {
    "code": "not_found",
    "message": "No domain matching 'yourdomain.com' was found on your account."
  }
}
Returned when you attempt to add a domain that is already attached to a site on your account.
409-response.json
{
  "error": {
    "code": "domain_already_exists",
    "message": "The domain 'yourdomain.com' is already attached to a site on your account."
  }
}
Returned when your API key is missing or invalid. See the Authentication guide for help.
401-response.json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}