Starhost Domains API: Add and Manage Custom Domains

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

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.

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

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

Status reference

Status	Description
`pending_verification`	The domain has been added but the required DNS records have not yet been detected.
`verified`	DNS records were confirmed and the domain is live. An SSL certificate has been provisioned.
`failed`	Verification failed. Check that the DNS records are correctly configured and try again.

SSL status values

SSL status	Description
`inactive`	SSL has not yet been provisioned, typically because verification is still pending.
`active`	An SSL certificate is active and HTTPS is enforced for the domain.
`error`	SSL 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

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

400 Bad Request — Missing required field

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."
  }
}

404 Not Found — Domain not found

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."
  }
}

409 Conflict — Domain already exists

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."
  }
}

401 Unauthorized

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."
  }
}

Overview

Nexus AI API

Starhost API

Starhost Domains API: Add and Manage Custom Domains

Add a custom domain

Request parameters

Example request

Example response

Get domain status

Path parameters

Example request

Example response

Domain status values

Remove a domain

Path parameters

Example request

Response

Error responses

​Add a custom domain

​Request parameters

​Example request

​Example response

​Get domain status

​Path parameters

​Example request

​Example response

​Domain status values

​Remove a domain

​Path parameters

​Example request

​Response

​Error responses

Add a custom domain

Request parameters

Example request

Example response

Get domain status

Path parameters

Example request

Example response

Domain status values

Remove a domain

Path parameters

Example request

Response

Error responses