> ## Documentation Index
> Fetch the complete documentation index at: https://help.verbosec.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Starhost Domains API: Add and Manage Custom Domains
> Use the Starhost API to add custom domains to your sites, verify DNS records, and check domain status programmatically.
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
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.
The custom domain name to add — for example, `"yourdomain.com"` or `"app.yourdomain.com"`. Do not include `https://` or a trailing slash.
### Example request
```bash add-domain.sh theme={null}
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
```json add-domain-response.json theme={null}
{
"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
The domain name to query — for example, `yourdomain.com`. This must match the domain you used when adding it.
### Example request
```bash get-domain.sh theme={null}
curl -X GET https://api.verbosec.com/v1/starhost/domains/yourdomain.com \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Example response
```json get-domain-response.json theme={null}
{
"domain": "yourdomain.com",
"site_id": "site_abc001",
"status": "verified",
"ssl": "active",
"created_at": "2025-01-15T12:00:00Z"
}
```
### Domain status values
| 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 | 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
The domain name to remove — for example, `yourdomain.com`.
### Example request
```bash delete-domain.sh theme={null}
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.
```json 400-response.json theme={null}
{
"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.
```json 404-response.json theme={null}
{
"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.
```json 409-response.json theme={null}
{
"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](/api-reference/authentication) for help.
```json 401-response.json theme={null}
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key."
}
}
```